Guide
From a new Discord bot to your first prompt: create it, invite it, connect your client, then ask.
Create the bot
The server acts through a Discord bot of your own. You create it once, in the Discord Developer Portal.
-
Create an application
Open the Developer Portal and sign in. Choose New Application, give it a name, and create it. The name is what your server sees.
-
Copy the token
Open the Bot page. Under the token, choose Reset Token and copy the new token. Discord shows it once: keep it somewhere safe. Anyone who holds it controls the bot.
-
Turn on the two privileged intents
On the same page, under Privileged Gateway Intents, turn on Server Members Intent and Message Content Intent, then save. The server asks for both when it connects: if one is off in the portal, Discord closes the connection with code
4014and every call fails. To run without one of them, see the intent flags. -
Note the Application ID
Open General Information and copy the Application ID. The invite link below needs it.
Invite it to your server
Replace YOUR_CLIENT_ID with the Application ID, then open the link. Pick your server and authorize. You need the Manage Server permission on that server.
https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot&permissions=2270827458424055
The link asks for the permissions most tools use, 22 in all. Untick the ones you do not want in the authorization screen; each tool page names the permissions it needs.
- Create Instant Invite
- Kick Members
- Ban Members
- Manage Channels
- Manage Server
- Add Reactions
- View Audit Log
- View Channel
- Send Messages
- Manage Messages
- Embed Links
- Read Message History
- Manage Nicknames
- Manage Roles
- Manage Webhooks
- Manage Events
- Manage Threads
- Create Public Threads
- Send Messages in Threads
- Moderate Members
- Create Events
- Pin Messages
Avoid Administrator unless a task needs it, such as pruning on a server that requires Administrator for it. Administrator ignores every channel overwrite, so a mistake would reach every channel.
Add it to your client
Most clients start the server with npx and read the same entry. Node.js 22 or later runs it; nothing else to install. Put your bot token in place of YOUR_BOT_TOKEN.
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
Open your client below for where the entry goes, or for a one-click install. A client that reaches the server by URL is under remote clients.
Claude Desktop
Bundle. Download discord-mcp.mcpb from the latest release and open it. Claude Desktop shows an install screen: enter the bot token there. The other settings are optional and match Configuration. The bundle runs on the Node.js built into Claude Desktop, so there is nothing else to install.
- On Windows, the file may not open in Claude Desktop. Install it from Settings > Extensions > Advanced settings > Install Extension instead.
- After you change a setting, quit and reopen Claude Desktop.
- The bundle does not update itself. After each release, download and open the new
discord-mcp.mcpb.
Config file. Or add the config from Quick start to claude_desktop_config.json, then restart Claude Desktop.
- macOS:
~/Library/ Application Support/ Claude/ claude_desktop_config.json - Windows:
%APPDATA%\Claude\ claude_desktop_config.json
Claude Code
Plugin. In a Claude Code session, run /, then /. Claude Code asks for the bot token and stores it as a secret, not in settings.json. If you skip that prompt, the server stays off until you set the token with /, which also changes the other settings. Restart Claude Code after setting or changing the token. The plugin also brings two skills, / and /. They read without a permission prompt, and nothing that changes Discord happens before you approve it.
Without the plugin. You can also add the server with claude mcp add, as before. Keep only one of the two, or every tool loads twice.
claude mcp add discord -e DISCORD_TOKEN=YOUR_BOT_TOKEN -- npx -y @pasympa/discord-mcp
Cursor
Use the Install in Cursor button, then replace YOUR_BOT_TOKEN. Or add the config from Quick start to ~/. See the Cursor MCP docs.
VS Code / GitHub Copilot
Use the Install in VS Code button: VS Code asks for the token and stores it as a secret. Or add this to .vscode/:
{ "inputs": [ { "type": "promptString", "id": "discord_token", "description": "Discord bot token", "password": true } ], "servers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "${input:discord_token}" } } }}
See the VS Code MCP docs.
Windsurf
Add the config from Quick start to ~/, then refresh the MCP servers list.
Codex CLI
codex mcp add discord --env DISCORD_TOKEN=YOUR_BOT_TOKEN -- npx -y @pasympa/discord-mcp
Cline
Open MCP Servers, then Configure, and add the config from Quick start to cline_mcp_settings.json.
Docker
{ "mcpServers": { "discord": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "DISCORD_TOKEN", "pasympa/discord-mcp:latest"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
From source
git clone https://github.com/PaSympa/discord-mcpcd discord-mcpnpm install && npm run build
{ "mcpServers": { "discord": { "command": "node", "args": ["/absolute/path/to/discord-mcp/dist/index.js"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
You can also put DISCORD_TOKEN=YOUR_BOT_TOKEN in a .env file at the project root; the server loads it on start.
Check that it works
Restart your client so it starts the server, then ask:
-
List my Discord servers.
-
What channels does my server have?
Your server in the answer means the token, the intents and the invite are right. An empty list means the bot is in no server yet: open the invite link again. An error names what is missing; Troubleshooting explains each one.
First prompts to try
Ask in plain language. The assistant picks the tools. Most clients ask you before each write unless you allow it; check how yours is set.
-
Summarize what's going on in #support and post a recap in #mod-log.
discord_(read-only)list_ channels discord_(read-only)read_ messages discord_(write)send_ embed -
Open a bug-tracker forum and file the two open bugs from the recap.
discord_(write)create_ forum_ channel discord_(destructive)set_ forum_ tags discord_(read-only)get_ forum_ tags discord_(write)create_ forum_ post -
A spam raid just hit #general. Preview the cleanup, then remove it.
discord_(read-only)read_ messages discord_(destructive)bulk_ delete_ messages -
Schedule a community call next Friday at 8 PM and announce it in #announcements.
discord_(write)create_ scheduled_ event discord_(write)create_ event_ invite discord_(write)send_ message -
Show me every permission overwrite in the server.
-
Create an invite to #welcome that expires in 24 hours.
-
Create a webhook on #deploys and post the release notes as an embed.
discord_(write)create_ webhook discord_(write)send_ webhook_ message
Recipes walk through these tasks step by step, with the prompts, the tools and the safety notes.
Remote clients over HTTP
The OpenAI Responses API, Codex and n8n can reach an MCP server by URL instead of starting it. For them, the server can run as a Streamable HTTP endpoint, protected by a static bearer token:
export DISCORD_TOKEN=YOUR_BOT_TOKENexport DISCORD_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" DISCORD_MCP_TRANSPORT=http npx -y @pasympa/discord-mcp
The endpoint is http:/. Every request must carry Authorization: Bearer <DISCORD_MCP_HTTP_TOKEN>. Toolsets, read-only mode and DISCORD_ALLOWED_GUILDS apply as on stdio.
The token is static: there is no OAuth, so this mode sits outside the MCP authorization spec. ChatGPT connectors need OAuth 2.1 or OpenAI's Secure MCP Tunnel, so this mode is not for ChatGPT.
In Docker, the server must listen on 0.0.0.0 inside the container. Publish the port on the host loopback only:
docker run --rm -p 127.0.0.1:3000:3000 \ -e DISCORD_TOKEN -e DISCORD_MCP_HTTP_TOKEN \ -e DISCORD_MCP_TRANSPORT=http -e DISCORD_MCP_HTTP_HOST=0.0.0.0 \ pasympa/discord-mcp:latest
OpenAI Responses API
The calls come from OpenAI's servers, so the endpoint must be reachable over public HTTPS, behind a reverse proxy or a tunnel. OpenAI does not keep the headers: send them with every request.
curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "YOUR_MODEL", "input": "List my Discord servers.", "tools": [{ "type": "mcp", "server_label": "discord", "server_url": "https://discord-mcp.example.com/mcp", "headers": { "Authorization": "Bearer YOUR_DISCORD_MCP_HTTP_TOKEN" }, "require_approval": { "never": { "read_only": true } }, "allowed_tools": ["discord_list_guilds", "discord_read_messages"] }] }'
With this require_approval, only the tools annotated readOnlyHint: true run without approval. See the OpenAI MCP guide.
Codex
Codex runs on your machine, so the local URL works. In ~/:
[mcp_servers.discord]url = "http://127.0.0.1:3000/mcp"bearer_token_env_var = "DISCORD_MCP_HTTP_TOKEN"
Or run codex mcp add discord --url http:/. Codex reads the token from that variable in its own environment. See the Codex MCP docs.
n8n
Add an MCP Client Tool node to an AI Agent:
- Endpoint:
http:// 127.0.0.1:3000/ mcp - Server Transport: HTTP Streamable
- Authentication: Header Auth, with a credential whose Name is
Authorizationand Value isBearer YOUR_DISCORD_MCP_HTTP_TOKEN
When n8n runs in Docker, 127.0.0.1 is the n8n container itself. Run the server in a container on the same Docker network, use http:/ as the endpoint, and add the container name to DISCORD_MCP_HTTP_ALLOWED_HOSTS. n8n Cloud needs a public HTTPS URL. See the n8n MCP Client Tool docs.
Security over HTTP
- Bind address. The default,
127.0.0.1, accepts connections from this machine only. Use0.0.0.0only inside a container, with the port published on127.0.0.1. - Token. Use at least 32 characters:
openssl rand -hex 32gives 64. Anyone who holds it acts as your bot, with the same toolsets, read-only mode and allow-list. To rotate it, restart the server with a new value. - HTTPS. The server speaks plain HTTP. To reach it from another machine, put it behind a reverse proxy or a tunnel that terminates TLS. Never publish the port on the Internet: the token would travel in clear text.
- Allowed hosts. A request needs a
Hostoflocalhost,127.0.0.1,[::1]or a name inDISCORD_MCP_HTTP_ALLOWED_HOSTS. Any request with anOriginheader is refused, so a web page cannot reach the server, even through DNS rebinding. nginx forwards its upstream address by default, which passes. Caddy forwards the public hostname: list it. - Stateless. Each POST to
/stands alone, and GET and DELETE answermcp 405. If a client drops the connection during a call, the Discord action still completes, so a retry can repeat a write.
Next steps
- Load only the toolsets you need. The full set costs about 35k tokens of context; a chat assistant needs a fraction of it.
- Turn on read-only mode to keep the 35 read-only tools and nothing else.
- Limit the server to some guilds when the bot sits in more than one.