Discord

discord-mcp

[npm] [CI] [License: MIT]

An MCP server that lets an LLM run a Discord server: 168 tools for messages, moderation, channels, roles, threads, events, invites, webhooks, AutoMod and more. Works with Claude, Cursor, VS Code, or any MCP client.

• Rich messages: embeds, Components V2, polls, files, replies — validated before they reach Discord, with errors that name the bad field.
• Interactions: role menus that survive restarts, plus a log of who clicked what.
• Secure by default: binds to 127.0.0.1, SSRF-guarded URL fetching, webhook tokens never echoed.

Quick start

1. Create a bot in the developer portal, invite it to your server, and enable the Message Content intent (Bot → Privileged Gateway Intents).
2. Add this to your MCP client's config (mcp.json, claude_desktop_config.json, .cursor/mcp.json, ...):

{  "mcpServers": {    "discord": {      "command": "npx",      "args": ["-y", "@willuhmjs/discord-mcp", "--stdio"],      "env": {        "DISCORD_TOKEN": "your-bot-token",        "DISCORD_GUILD_ID": "your-server-id"      }    }  }}

VS Code uses "servers" instead of "mcpServers". On Windows, if the client can't find npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@willuhmjs/discord-mcp", "--stdio"].

Claude Code — one command:

claude mcp add discord -e DISCORD_TOKEN=... -e DISCORD_GUILD_ID=... -- npx -y @willuhmjs/discord-mcp --stdio

Docker — a long-running HTTP server at http://127.0.0.1:8085/mcp:

docker run --rm -e DISCORD_TOKEN=... -p 127.0.0.1:8085:8085 ghcr.io/willuhmjs/discord-mcp

Requires Node.js 22+ for npx.

Configuration

In HTTP mode, POST /mcp serves MCP (stateful sessions via Mcp-Session-Id) and GET /health returns 200 once the bot is connected.

Keeping the HTTP endpoint private

The HTTP endpoint has no authentication: anyone who can reach it can use every tool as the bot. Keep it on loopback or a private network. On a shared machine, other accounts can still reach a loopback port, so use a Unix socket that only you can open:

mkdir -m 700 ~/.mcpMCP_SOCKET=~/.mcp/discord.sock DISCORD_TOKEN=... npx @willuhmjs/discord-mcpcurl --unix-socket ~/.mcp/discord.sock http://localhost/health

The socket is created with mode 600. Avoid network file systems such as NFS. The Docker image binds 0.0.0.0, so keep that container on an internal network. stdio mode has no network exposure at all.

Tools

Every tool, with its parameters and the Discord permission it needs, is listed in docs/TOOLS.md, along with the conventions (string IDs, JSON-string payloads, reason for the audit log) and message/component formats.

Security

• Every URL a tool fetches (emoji, stickers, files, avatars) goes through one guarded fetcher: http/https only, private/loopback/metadata IPs blocked before the request and after every redirect, size and time limits.
• Webhook tokens are credentials: create_webhook returns the URL once, and no list/get tool shows it.
• No tool reads the server's filesystem.

Development

npm cinpm run build       # tsc -> dist/npm test            # vitest, no Discord token needednpm run typecheck

A contract test locks every tool name and parameter set against tests/fixtures/tool-contract.json. TESTING.md is the manual checklist for a run in a real test server.

Releases are automated: commits on main using Conventional Commits (feat:, fix:, feat!:) feed a release PR; merging it publishes to npm, the MCP Registry and GHCR.

License

MIT