discord-mcp

discord-mcp connects Claude, 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.

See it in action

[Claude Code previews a cleanup of four spam messages in #general with a dry run, then deletes them, on a demo Discord server]

_{Calls made live with Claude Code on a demo server; the panel summarizes their results. The Discord window shows real captures, except that the spot of each new message or post stays blank until it appears.}

What you can ask

Quick start

1. 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.

2. Invite it to your server. Replace YOUR_CLIENT_ID with 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.

3. Add it to your client. Use a button above, or paste this into your client's MCP config:

   json

   {  "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.

Expose only what you need

The full set of 100 tools costs about 32k 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.

"env": {  "DISCORD_TOKEN": "YOUR_BOT_TOKEN",  "DISCORD_MCP_TOOLSETS": "discovery,messages"}

Context sizes are measured on the tools/list response (bytes divided by 4). Toolsets: discovery, messages, channels, permissions, members (includes kick, ban and timeout), roles, moderation (the audit log), screening, stats, forums, webhooks, scheduled_events, invites, dm. A toolset brings its whole module, destructive tools included; an unknown name stops the server at startup instead of exposing everything.

Safety

• Your bot, your permissions. The server can only do what the bot's Discord permissions allow.
• Preview before mass actions. discord_bulk_delete_messages, discord_bulk_ban, discord_prune_members and discord_delete_channel run as a dry run by default and report what would happen. Pass dry_run: false to apply.
• Stay in your servers. DISCORD_ALLOWED_GUILDS restricts 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 declares destructiveHint, so clients can approve reads automatically and ask before destructive calls.
• 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.

Clients

claude mcp add discord -e DISCORD_TOKEN=YOUR_BOT_TOKEN -- npx -y @pasympa/discord-mcp

{  "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}"      }    }  }}

codex mcp add discord --env DISCORD_TOKEN=YOUR_BOT_TOKEN -- npx -y @pasympa/discord-mcp

{  "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"      }    }  }}

Configuration

The intent flags only change what the bot requests when it connects. Requesting a privileged intent that is not enabled in the Developer Portal closes the connection with code 4014; set the flag to false to connect anyway. What the tools can read is governed by the portal toggles: every message is fetched over the REST API, which Discord gates on the portal setting alone. With Message Content off in the portal, message bodies come back empty (content, embeds, attachments), except the bot's own messages, DMs and messages that mention the bot; with Server Members off, member listing fails.

Tools

100 tools in 14 toolsets. Each one documents its permissions, side effects and return shape in its description.

Troubleshooting

• Every call fails with close code 4014. The bot requests a privileged intent that is off in the Developer Portal. Enable Server Members and Message Content there, or set DISCORD_GUILD_MEMBERS=false / DISCORD_MESSAGE_CONTENT=false.
• Messages come back with empty text. Message Content is off in the portal. Enable it; the flag alone does not change what the REST API returns.
• A channel reads as empty. The bot lacks Read Message History there: Discord returns an empty list rather than an error.
• Missing Access or Missing Permissions. The bot cannot see the channel, or the target role or member sits above the bot's highest role. Check overwrites with discord_get_channel_permissions.
• Finding IDs. Enable Developer Mode in Discord (Settings, Advanced), then right-click a server, channel or user and choose Copy ID.

Contributing

Contributions are welcome. CONTRIBUTING.md covers the module layout, the tool definition quality bar and the release flow. Report vulnerabilities as described in SECURITY.md.

License

MIT, see LICENSE. discord-mcp is an independent open-source project, not affiliated with or endorsed by Discord Inc.

VS Code and VS Code Insiders icons: Codicons © Microsoft Corporation, licensed under CC BY 4.0.