Let your AI assistant run your Discord server.
discord-mcp connects Claude, Codex, Cursor, VS Code and any other MCP client to your Discord server through your own bot. Ask in plain language: your assistant reads channels, answers, moderates, and manages roles, channels, forums and events, with 100 tools behind it.
Add it to your client
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.
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
- macOS:
~/Library/ Application Support/ Claude/ claude_desktop_config.json - Windows:
%APPDATA%\Claude\ claude_desktop_config.json
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
Use the Install in Cursor button, then replace YOUR_BOT_TOKEN. Or add the config from Quick start to ~/. See the Cursor MCP docs.
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
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.
Add the config from Quick start to ~/, then refresh the MCP servers list.
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
codex mcp add discord --env DISCORD_TOKEN=YOUR_BOT_TOKEN -- npx -y @pasympa/discord-mcp
Open MCP Servers, then Configure, and add the config from Quick start to cline_mcp_settings.json.
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
{ "mcpServers": { "discord": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "DISCORD_TOKEN", "pasympa/discord-mcp:latest"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
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.
Replace YOUR_BOT_TOKEN with your bot's token, created in three steps. The server runs on Node.js 22 or later.
See it work
One request from the recorded demo session. The assistant reads the channel, previews the cleanup with a dry run, then deletes.
A spam raid just hit #general. Preview the cleanup, then remove it.
-
discord-mcp discord_
read_ messages (#general, limit: 10)7 messages, the last 4 are spam -
discord-mcp discord_
bulk_ delete_ messages (count: 4)Dry run: 4 of the 4 most recent messages in #general would be deleted -
discord-mcp discord_
bulk_ delete_ messages (count: 4, dry_run: false)Deleted 4 messages in #general
-
Catch up on a busy channel
Summarize what's going on in #support and post a recap in #mod-log.
Called in the recorded session
discord_(read-only)list_ channels discord_(read-only)read_ messages discord_(write)send_ embed -
Turn feedback into a tracker
Open a bug-tracker forum and file the two open bugs from the recap.
Called in the recorded session
discord_(write)create_ forum_ channel discord_(destructive)set_ forum_ tags discord_(read-only)get_ forum_ tags discord_(write)create_ forum_ post -
Stop a spam raid safely
A spam raid just hit #general. Preview the cleanup, then remove it.
Called in the recorded session
discord_(read-only)read_ messages discord_(destructive)bulk_ delete_ messages -
Run community events
Schedule a community call next Friday at 8 PM and announce it in #announcements.
Called in the recorded session
discord_(write)create_ scheduled_ event discord_(write)create_ event_ invite discord_(write)send_ message -
Audit permissions
Show me every permission overwrite in the server.
Tools for it, from their descriptions
discord_(read-only)audit_ permissions -
Welcome people
Create an invite to #welcome that expires in 24 hours.
Tools for it, from their descriptions
discord_(write)create_ invite -
Automate notifications
Create a webhook on #deploys and post the release notes as an embed.
Tools for it, from their descriptions
discord_(write)create_ webhook discord_(write)send_ webhook_ message
Set it up in three steps
A bot of your own, invited to your server, then one entry in your client's MCP config.
Read the full guide-
Create a bot
In the Discord Developer Portal, create an application, open Bot, then Reset Token and copy it. On the same page, enable Server Members Intent and Message Content Intent.
-
Invite it to your server
Replace
YOUR_CLIENT_IDwith the Application ID from General Information, then open the link:https://discord.com/oauth2/authorize?client_id= YOUR_CLIENT_ID& scope= bot& permissions= 2270827458424055 It requests the permissions the tools use. Remove the ones you do not need in the authorization screen.
-
Add it to your client
Use a button above, or paste this into your client's MCP config:
{ "mcpServers": { "discord": { "command": "npx", "args": ["-y", "@pasympa/discord-mcp"], "env": { "DISCORD_TOKEN": "YOUR_BOT_TOKEN" } } }}
npx downloads and runs the server (Node.js 22 or later); nothing else to install. Per-client instructions are under Clients.
Safety
The server acts through your bot and stops where its permissions stop. Mass actions show what they would do before they do it.
-
Your bot, your permissions
The server can only do what the bot's Discord permissions allow.
-
Preview before mass actions
discord_(destructive),bulk_ delete_ messages discord_(destructive),bulk_ ban discord_(destructive) andprune_ members discord_(destructive) run as a dry run by default and report what would happen. Passdelete_ channel dry_run: falseto apply. -
Stay in your servers
DISCORD_ALLOWED_GUILDSrestricts every call to the guilds you list, whether the target is addressed by guild, channel, thread, webhook or invite. -
Clear annotations
Every tool declares
readOnlyHint, and every write tool declaresdestructiveHint, so clients can approve reads automatically and ask before destructive calls.35 read-only47 write18 destructive
-
Read-only mode
With
DISCORD_MCP_READ_ONLY=true, the server lists only the tools that declarereadOnlyHint: true. A call to any other tool fails as an unknown tool. Two reads stay sensitive.discord_(read-only) returns webhook tokens, and a token lets anyone post through its webhook without this server.list_ webhooks discord_(read-only) reads the bot's direct messages with a user. To hide both, leaveread_ dms webhooksanddmout ofDISCORD_MCP_TOOLSETS. -
Keep the token out of files
Prefer your client's secret prompt (the VS Code button asks for the token) over a config file you might commit.
Load only what you need
The full set of 100 tools costs about 35k tokens of context when a client loads them all. Most assistants need a fraction of it: set DISCORD_MCP_TOOLSETS to the toolsets you want.
Set DISCORD_MCP_READ_ONLY=true to keep only the 35 tools annotated readOnlyHint: true, about 14k tokens. It narrows DISCORD_MCP_TOOLSETS instead of replacing it: discovery,messages then exposes 11 tools, about 5k tokens. A selection with no read-only tool left, such as channels alone, stops the server at startup.
DISCORD_MCP_TOOLSETS=discovery,messages
Context sizes are measured on the tools/ response (bytes divided by 4).
Browse all 100 tools
Every tool documents its permissions, side effects and return shape. The catalog adds search, risk filters, and input and output schemas.
Open the catalog- Discovery4 tools4 read-only Find servers and channels, and the IDs most other tools need.
- Messages21 tools7 read-only, 11 write, 3 destructive Read, search, send, edit, react to, pin, forward and delete messages, and manage threads.
- Channels8 tools7 write, 1 destructive Create, edit, move, clone, follow and delete channels.
- Permissions6 tools2 read-only, 2 write, 2 destructive Inspect, set, copy and reset channel permission overwrites.
- Members11 tools4 read-only, 3 write, 4 destructive List and search members, set nicknames, and kick, ban, time out or prune.
- Roles9 tools2 read-only, 6 write, 1 destructive Create, edit, assign, order and delete roles.
- Moderation1 tool1 read-only Read the audit log.
- Screening2 tools1 read-only, 1 write Read and update the membership screening form.
- Stats1 tool1 read-only A snapshot of server metrics.
- Forums10 tools4 read-only, 4 write, 2 destructive Forum channels, posts, replies and tags.
- Webhooks8 tools2 read-only, 4 write, 2 destructive Create webhooks and post, edit or delete messages through them.
- Scheduled events7 tools3 read-only, 3 write, 1 destructive Create and manage events, see who is interested, and invite people to them.
- Invites5 tools3 read-only, 1 write, 1 destructive List, inspect, create and revoke invites.
- Direct messages7 tools1 read-only, 5 write, 1 destructive Send, read, edit and delete direct messages.