discord-mcp

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.

Install in VS CodeInstall in VS Code InsidersInstall in CursorInstall in Claude Desktop

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.

claude_desktop_config.json
{  "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 /plugin marketplace add PaSympa/discord-mcp, then /plugin install discord-mcp@pasympa. 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 /plugin configure discord-mcp@pasympa, which also changes the other settings. Restart Claude Code after setting or changing the token. The plugin also brings two skills, /discord-mcp:channel-digest and /discord-mcp:moderation-sweep. 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.

Terminal
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 ~/.cursor/mcp.json. See the Cursor MCP docs.

Install in Cursor

~/.cursor/mcp.json
{  "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/mcp.json:

Install in VS CodeInstall in VS Code Insiders

.vscode/mcp.json
{  "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 ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers list.

~/.codeium/windsurf/mcp_config.json
{  "mcpServers": {    "discord": {      "command": "npx",      "args": ["-y", "@pasympa/discord-mcp"],      "env": {        "DISCORD_TOKEN": "YOUR_BOT_TOKEN"      }    }  }}
Terminal
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.

cline_mcp_settings.json
{  "mcpServers": {    "discord": {      "command": "npx",      "args": ["-y", "@pasympa/discord-mcp"],      "env": {        "DISCORD_TOKEN": "YOUR_BOT_TOKEN"      }    }  }}
MCP config
{  "mcpServers": {    "discord": {      "command": "docker",      "args": ["run", "--rm", "-i", "-e", "DISCORD_TOKEN", "pasympa/discord-mcp:latest"],      "env": {        "DISCORD_TOKEN": "YOUR_BOT_TOKEN"      }    }  }}
Terminal
git clone https://github.com/PaSympa/discord-mcpcd discord-mcpnpm install && npm run build
MCP config
{  "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.

Claude CodeSummary of the real tool calls

A spam raid just hit #general. Preview the cleanup, then remove it.

  1. (#general, limit: 10)
    7 messages, the last 4 are spam
  2. (count: 4)
    Dry run: 4 of the 4 most recent messages in #general would be deleted
  3. (count: 4, dry_run: false)
    Deleted 4 messages in #general
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

Ask in plain language; the assistant picks the tools.

See the recipes

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
  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:

    Invite 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:

    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_bulk_delete_messages (destructive), discord_bulk_ban (destructive), discord_prune_members (destructive) and discord_delete_channel (destructive) 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.

    35 read-only47 write18 destructive

  • Read-only mode

    With DISCORD_MCP_READ_ONLY=true, the server lists only the tools that declare readOnlyHint: true. A call to any other tool fails as an unknown tool. Two reads stay sensitive. discord_list_webhooks (read-only) returns webhook tokens, and a token lets anyone post through its webhook without this server. discord_read_dms (read-only) reads the bot's direct messages with a user. To hide both, leave webhooks and dm out of DISCORD_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.

Open the toolset builder
Profiles from the README

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.

Environment
DISCORD_MCP_TOOLSETS=discovery,messages

Context sizes are measured on the tools/list 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