discord-mcp

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.

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

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

  3. 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 4014 and every call fails. To run without one of them, see the intent flags.

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

Invite link
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.

MCP config
{  "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 /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
Cursor

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

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

Windsurf

Add the config from Quick start to ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers list.

Codex CLI
Terminal
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
MCP config
{  "mcpServers": {    "discord": {      "command": "docker",      "args": ["run", "--rm", "-i", "-e", "DISCORD_TOKEN", "pasympa/discord-mcp:latest"],      "env": {        "DISCORD_TOKEN": "YOUR_BOT_TOKEN"      }    }  }}
From source
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.

Next: check that it works.

Check that it works

Restart your client so it starts the server, then ask:

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.

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:

Terminal
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://127.0.0.1:3000/mcp. 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:

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

Terminal
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 ~/.codex/config.toml:

~/.codex/config.toml
[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://127.0.0.1:3000/mcp --bearer-token-env-var DISCORD_MCP_HTTP_TOKEN. 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 Authorization and Value is Bearer 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://CONTAINER_NAME:3000/mcp 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. Use 0.0.0.0 only inside a container, with the port published on 127.0.0.1.
  • Token. Use at least 32 characters: openssl rand -hex 32 gives 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 Host of localhost, 127.0.0.1, [::1] or a name in DISCORD_MCP_HTTP_ALLOWED_HOSTS. Any request with an Origin header 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 /mcp stands alone, and GET and DELETE answer 405. If a client drops the connection during a call, the Discord action still completes, so a retry can repeat a write.

Next steps