discord-mcp

Control a Discord bot from an AI model through Model Context Protocol. Each supported Discord operation has its own tool, with validated inputs, structured results and links to the official Discord reference.

The server runs locally over stdio and controls one bot across all the servers it can access. The AI model runs in your MCP client.

Install

Install Node.js 24.17 or newer. Download the .tgz package from GitHub Releases, then install it, replacing VERSION with the downloaded version:

npm install -g ./yoraudev-discord-mcp-VERSION.tgz

Releases are published after product changes merge from dev into main. There is no npm registry publication. To build from source:

git clone https://github.com/yoraudev/discord-mcp.git
cd discord-mcp
npm ci
npm run build

Related MCP server: MCP Server Toolkit

Connect

Create an application and bot in the Discord Developer Portal, invite it to your server, and add this entry to your MCP client's configuration:

{
  "mcpServers": {
    "discord": {
      "command": "discord-mcp",
      "env": {
        "DISCORD_BOT_TOKEN": "YOUR_BOT_TOKEN",
        "DISCORD_APPLICATION_ID": "YOUR_APPLICATION_ID"
      }
    }
  }
}

For a source checkout, use node as the command and the absolute path to dist/index.js as its argument. Windows clients that cannot resolve a global npm command can also launch node with the installed package's absolute entrypoint. Credentials belong in environment variables. .env is loaded by npm start; other launchers must explicitly pass environment variables or Node's env-file option.

Ask your model to inspect discord_status, list channels, send a message, manage roles, configure application commands, or read events using discord_events_poll. The complete tool catalog is produced from the registered input schemas.

Capabilities

Features remain subject to Discord permissions, role hierarchy, intents, application eligibility and documented API restrictions. See the coverage inventory, setup guide and architecture.

Configuration

Good to know

• Audio connections, playback, recording, receiving, TTS, soundboard and voice messages are excluded. Voice/Stage channel administration and member move/mute/deafen operations are supported.

• OAuth2, event history, webhook handles and interaction rules live in memory and reset when the process ends. Keep the MCP client connected to receive events.

• Poll with the last returned cursor. A gap reports overwritten events; cursors from a previous process are rejected. Discord reconnect events report possible delivery gaps.

• Deferrable interactions are acknowledged automatically. Configure immediate modal/autocomplete rules before users trigger them. Use the interaction handle from the event to edit the original response or send followups.

• Webhook tokens returned by Discord are replaced with webhook_handle; interaction tokens are replaced with interaction_handle. Handles expire and cannot be reused after a restart.

• The webhook receiver needs a public HTTPS reverse proxy to reach the local port. Hosting and tunnels are not created by this project.

Development

npm ci
npm run check
npm run docs:generate
npm pack

Use npm run reference:sync to refresh the ignored official-document cache, then node tools/build-reference.mjs to rebuild the reviewed inventory. Review the inventory and schema overrides before accepting upstream changes. Reference updates must include regenerated documentation and contract tests.

The development guide describes validation, live Discord testing and release setup. Follow AGENTS.md when changing the project.

License

Free to use, modify and redistribute under the project's attribution and origin-preservation conditions. See LICENSE.