discord-mcp

Purpose

discord-mcp is an MCP (Model Context Protocol) server for controlling Discord through natural language. It can be connected to Claude Desktop, Claude Code, Cursor, VS Code Copilot, or any MCP-compatible client, allowing users to manage an entire Discord server conversationally, including operations on messages, channels, roles, permissions, members, and moderation.

Main Capabilities

• Provides 95+ tools, covering messages, channels, roles, permissions, moderation, forums, Webhooks, scheduled events, invites, direct messages, embedded content, and more.
• Supports multiple servers (multi-guild), without being locked to a single GUILD_ID.
• Lightweight: TypeScript + Node.js, package size about 70kB, Docker image about 73MB (compared with Java solutions at 400MB+).
• Modular: clear architecture, making it easy to extend with new tools.
• Two installation methods: npm or Docker.

Usage

Add the server configuration to your MCP client configuration, and replace YOUR_TOKEN_HERE with the bot token. Using npx requires no installation.

• Claude Desktop: add the configuration to claude_desktop_config.json. The macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json; the Windows path is %APPDATA%\Claude\claude_desktop_config.json. After saving, restart Claude Desktop.
• Cursor: add the configuration to ~/.cursor/mcp.json.
• VS Code: add it to .vscode/mcp.json.

You can also create a .env file in the project root directory; the server automatically loads it via dotenv.

Environment Variables

• Since 2.1.1, the server no longer requests the GuildMessages intent: it does not subscribe to message events, and all returned messages are obtained through REST; the connection intent does not restrict this operation. DISCORD_MESSAGE_CONTENT only affects whether the Message Content intent is requested when connecting, and does not change the content returned by any tool.
• These flags only control which gateway intents the server requests during identification. Requesting a privileged intent that is not enabled in the Developer Portal will cause the connection to fail on the first tool call (close code 4014); setting the flag to false allows the connection to continue.
• Data access is controlled by portal toggles, not by these flags: the server reads everything through the REST API, and Discord restricts it only according to the portal settings. When the portal toggle is enabled, setting the flag to false will not lose any content. When the portal toggle is disabled, the corresponding data is restricted: message bodies are returned empty (content, embeds, attachments; except for the bot's own messages, direct messages, and messages that mention the bot), and member lists fail; enabling the toggle in the portal restores them.
• Toolsets (DISCORD_MCP_TOOLSETS): discovery, messages, channels, permissions, members, roles, moderation, screening, stats, forums, webhooks, scheduled_events, invites, dm. For example, DISCORD_MCP_TOOLSETS=discovery,messages,members exposes only the discovery, message, and member tools. Note: a toolset includes its entire module, including destructive tools (messages includes bulk deletion; members includes kick/ban); use DISCORD_ALLOWED_GUILDS and dry-run defaults to constrain it. Only the listed toolsets are published and callable. Unknown names will cause the server to fail to start, rather than silently exposing everything (an empty value is treated as unset, exposing everything).

Creating a Discord Bot

1. Go to discord.com/developers/applications
2. New Application > name it
3. Bot tab > Reset Token > copy the token
4. Enable Privileged Gateway Intents (the server requests them by defaultBoth, but the portal toggle for the new Discord app is OFF): Server Members Intent, Message Content Intent. Important: if the bot requests a privileged intent that is not enabled here, Discord will close the connection with code 4014, and all tool calls will fail. Enable both, or stop requesting unneeded intents via the environment variables above.
5. OAuth2 > URL Generator: For Scopes select bot; for Permissions select Send Messages, Read Message History, Manage Channels, Manage Roles, Kick Members, Ban Members, Moderate Members, View Audit Log, Manage Messages, Manage Threads, Add Reactions, Manage Guild, Manage Webhooks, Manage Events, Create Events, Create Instant Invite, Manage Nicknames, Pin Messages, Embed Links, Create Public Threads, Send Messages in Threads.
6. Copy the generated URL and invite the bot to the server.

Available Tools (99)

• Discovery & Navigation (4 tools)
• Messages (20 tools)
• Channels (8 tools)
• Channel Permissions (6 tools)
• Members (11 tools)
• Roles (9 tools)
• Forums (10 tools)
• Webhooks (8 tools)
• Scheduled Events (7 tools)
• Direct Messages (7 tools)
• Invites (5 tools)
• Moderation & Screening (3 tools)

Finding Discord IDs

Enable Developer Mode in Discord: Settings > Advanced > Developer Mode. Then right-click the server, channel, or user > Copy ID.

Project Structure and Extension

Adding a new tool:

1. Create a new file in src/tools/ (e.g., events.ts).
2. Use defineTool({ name, description, annotations, schema, handle }) to declare each tool, and export defineModule([...]) as the default export.
3. Import it in src/tools/index.ts and add it to allToolsets (the key is its DISCORD_MCP_TOOLSETS name).

Security Recommendations

• Never commit the Discord token to Git.
• Use environment variables or a .env file (not included in version control).
• Grant the bot only the permissions it needs.
• Use DISCORD_ALLOWED_GUILDS to restrict the server to specific servers.
• Irreversible large-scale operations (bulk_ban, prune_members, bulk_delete_messages, delete_channel) use dry_run preview by default; they are only executed when dry_run:false is passed.

Contributing

Contributions are welcome: Fork the repository, create a feature branch (git checkout -b feature/my-feature), follow the modular structure (see Adding a new tool), commit your changes, and open a pull request.

License

MIT, see LICENSE for details.