Run your Discord from Claude, Codex, Cursor or VS Code: messages, moderation, roles, forums, events
io.github.PaSympa/discord-mcp (MCP Server)
A lightweight, multi-guild Discord Model Context Protocol (MCP) server that provides 95+ tools. It targets MCP compatibility and is implemented in TypeScript/Node.js with Discord.js v14, supporting multi-guild Discord integrations.
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.
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
You want to
Ask your assistant
Catch up on a busy channel
"Summarize what's going on in #support and post a recap in #mod-log."
Turn feedback into a tracker
"Open a bug-tracker forum and file the two open bugs from the recap."
Stop a spam raid safely
"A spam raid just hit #general. Preview the cleanup, then remove it."
Run community events
"Schedule a community call next Friday at 8 PM and announce it in #announcements."
Audit permissions
"Show me every permission overwrite in the server."
Welcome people
"Create an invite to #welcome that expires in 24 hours."
Automate notifications
"Create a webhook on #deploys and post the release notes as an embed."
Quick start
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.
Invite it to your server. Replace YOUR_CLIENT_ID with the Application ID from General Information, then open the link:
npx downloads and runs the server (Node.js 22 or later); nothing else to install. Per-client instructions are under Clients.
Expose 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.
Context sizes are measured on the tools/list response (bytes divided by 4). Toolsets: discovery, messages, channels, permissions, members (includes kick, ban and timeout), roles, moderation (the audit log), screening, stats, forums, webhooks, scheduled_events, invites, dm. A toolset brings its whole module, destructive tools included; an unknown name stops the server at startup instead of exposing everything.
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.
Safety
Your bot, your permissions. The server can only do what the bot's Discord permissions allow.
Preview before mass actions.discord_bulk_delete_messages, discord_bulk_ban, discord_prune_members and discord_delete_channel 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.
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 returns webhook tokens, and a token lets anyone post through its webhook without this server. discord_read_dms 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.
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.
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.
bash
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.
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:
You can also put DISCORD_TOKEN=YOUR_BOT_TOKEN in a .env file at the project root; the server loads it on start.
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:
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:
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.
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.
Configuration
Variable
Default
Description
DISCORD_TOKEN
none
Required. Bot token.
DISCORD_MCP_TOOLSETS
all
Comma-separated toolsets to expose (see Expose only what you need). Unset, empty or all exposes every tool.
DISCORD_MCP_READ_ONLY
false
Set to true to expose only the tools annotated readOnlyHint: true. Accepts true/false, 1/0, yes/no or on/off; any other value stops the server at startup.
DISCORD_ALLOWED_GUILDS
all
Comma-separated guild IDs the server may act on. Calls that target any other guild are rejected, whether addressed by guild ID, channel ID, thread ID, webhook or invite code.
DISCORD_MESSAGE_CONTENT
true
Set to false to stop requesting the Message Content privileged intent at connect time.
DISCORD_GUILD_MEMBERS
true
Set to false to stop requesting the Server Members privileged intent at connect time.
DISCORD_MCP_TRANSPORT
stdio
stdio, or http to serve Streamable HTTP (see Remote clients over HTTP). Any other value stops the server at startup.
DISCORD_MCP_HTTP_TOKEN
none
Required in http mode. Bearer token every request must carry: at least 32 characters from the RFC 6750 b64token alphabet (letters, digits, -._~+/, trailing =), different from DISCORD_TOKEN.
DISCORD_MCP_HTTP_HOST
127.0.0.1
Address to listen on in http mode.
DISCORD_MCP_HTTP_PORT
3000
Port to listen on in http mode.
DISCORD_MCP_HTTP_ALLOWED_HOSTS
none
Comma-separated hostnames, without port, accepted in the Host header besides localhost, 127.0.0.1 and [::1], such as the public name a reverse proxy forwards.
The intent flags only change what the bot requests when it connects. Requesting a privileged intent that is not enabled in the Developer Portal closes the connection with code 4014; set the flag to false to connect anyway. What the tools can read is governed by the portal toggles: every message is fetched over the REST API, which Discord gates on the portal setting alone. With Message Content off in the portal, message bodies come back empty (content, embeds, attachments), except the bot's own messages, DMs and messages that mention the bot; with Server Members off, member listing fails.
Tools
100 tools in 14 toolsets. Each one documents its permissions, side effects and return shape in its description.
Discovery (4 tools)
Tool
Description
discord_list_guilds
List all servers the bot is connected to
discord_get_guild_info
Get detailed guild info (name, members, channels, roles, boosts)
discord_list_channels
List all channels in a guild grouped by category
discord_find_channel_by_name
Find a channel by name (partial match)
Messages (21 tools)
Tool
Description
discord_read_messages
Read messages, paging back through history
discord_send_message
Send a plain text message
discord_reply_message
Reply to a specific message
discord_edit_message
Edit a message sent by the bot
discord_delete_message
Delete a specific message
discord_add_reaction
Add a reaction emoji to a message
discord_remove_reactions
Remove reactions (all, by emoji, or by user)
discord_get_reactions
List users who reacted with a specific emoji
discord_create_thread
Create a thread from a message or standalone
discord_list_channel_threads
List a text channel's threads, paged
discord_bulk_delete_messages
Delete multiple messages at once (2-100)
discord_send_embed
Send a rich embed with all options
discord_edit_embed
Edit an embed previously sent by the bot
discord_send_multiple_embeds
Send up to 10 embeds in a single message
discord_pin_message
Pin or unpin a message
discord_get_message_attachments
List a message's attachments with download urls
discord_fetch_pinned_messages
List a channel's pinned messages, paged
discord_search_messages
Search messages by keyword (last 100)
discord_search_guild_messages
Search across every channel using Discord's search index
discord_crosspost_message
Publish a message to announcement channel followers
discord_forward_message
Forward a message to another channel
Channels (8 tools)
Tool
Description
discord_create_channel
Create a text, voice channel or category
discord_delete_channel
Delete a channel
discord_edit_channel
Edit name, topic, slowmode, NSFW flag
discord_move_channel
Move a channel into/out of a category
discord_clone_channel
Clone a channel with its permissions
discord_set_channel_position
Set display position within a category
discord_follow_announcement_channel
Follow an announcement channel
discord_lock_channel_permissions
Sync permissions with parent category
Channel permissions (6 tools)
Tool
Description
discord_get_channel_permissions
List all permission overwrites on a channel
discord_set_role_permission
Allow/deny permissions for a role on a channel
discord_set_member_permission
Allow/deny permissions for a member on a channel
discord_reset_channel_permissions
Remove all overwrites (reset to inherited)
discord_copy_permissions
Copy overwrites from one channel to another
discord_audit_permissions
Full permission audit for all channels
Members (11 tools)
Tool
Description
discord_list_members
List guild members with their roles
discord_get_member_info
Detailed member info (roles, permissions, join date)
discord_search_members
Search members by username or nickname
discord_set_nickname
Set or clear a member's nickname
discord_kick_member
Kick a member
discord_ban_member
Ban a member (optionally delete recent messages)
discord_unban_member
Unban a user
discord_bulk_ban
Ban multiple users at once (raid mitigation)
discord_list_bans
List all banned users
discord_timeout_member
Timeout a member (0 to remove)
discord_prune_members
Remove inactive members (with dry run)
Roles (9 tools)
Tool
Description
discord_list_roles
List all roles with permissions and member count
discord_create_role
Create a new role
discord_edit_role
Edit a role (name, color, permissions, hoist, mentionable)
discord_delete_role
Delete a role
discord_add_role
Assign a role to a member
discord_remove_role
Remove a role from a member
discord_get_role_members
List all members with a specific role
discord_set_role_position
Change a role's position in the hierarchy
discord_set_role_icon
Set a custom icon or unicode emoji on a role
Forums (10 tools)
Tool
Description
discord_get_forum_channels
List all forum channels in a guild
discord_create_forum_channel
Create a new forum channel
discord_create_forum_post
Create a post/thread in a forum
discord_get_forum_post
Get a post's details and messages
discord_list_forum_threads
List threads (active + archived)
discord_reply_to_forum
Reply to a forum post
discord_delete_forum_post
Delete a forum thread
discord_get_forum_tags
Get available tags
discord_set_forum_tags
Set/update tags on a forum
discord_update_forum_post
Update title, archived, locked, tags
Webhooks (8 tools)
Tool
Description
discord_create_webhook
Create a webhook on a channel
discord_send_webhook_message
Send via webhook (custom username/avatar, embeds)
discord_edit_webhook
Edit a webhook's name, avatar, or channel
discord_delete_webhook
Delete a webhook
discord_list_webhooks
List webhooks for a channel or guild
discord_edit_webhook_message
Edit a message sent by a webhook
discord_delete_webhook_message
Delete a message sent by a webhook
discord_fetch_webhook_message
Fetch a specific webhook message
Scheduled events (7 tools)
Tool
Description
discord_list_scheduled_events
List all scheduled events in a guild
discord_get_scheduled_event
Get detailed info about a scheduled event
discord_create_scheduled_event
Create a voice, stage, or external event
discord_edit_scheduled_event
Edit an existing scheduled event
discord_delete_scheduled_event
Delete a scheduled event
discord_get_event_subscribers
Get users who marked "Interested"
discord_create_event_invite
Create an invite linked to an event
Direct messages (7 tools)
Tool
Description
discord_send_dm
Send a direct message to a user by their user ID
discord_send_dm_embed
Send an embed in a DM to a user
discord_read_dms
Read message history from a DM conversation
discord_reply_dm
Reply to a specific DM message
discord_edit_dm
Edit a previously sent DM (text)
discord_edit_dm_embed
Edit a previously sent DM embed
discord_delete_dm
Delete a DM message
Invites (5 tools)
Tool
Description
discord_list_invites
List all active invites in a guild
discord_list_channel_invites
List invites for a specific channel
discord_get_invite
Get details about an invite by its code
discord_create_invite
Create an invite link for a channel
discord_delete_invite
Revoke an invite
Moderation, screening and stats (4 tools)
Tool
Description
discord_get_audit_log
Fetch the guild audit log
discord_get_membership_screening
Get the membership screening form
discord_update_membership_screening
Update screening rules for new members
discord_get_server_stats
Server stats: members, channels, roles, boost level
Troubleshooting
Every call fails with close code 4014. The bot requests a privileged intent that is off in the Developer Portal. Enable Server Members and Message Content there, or set DISCORD_GUILD_MEMBERS=false / DISCORD_MESSAGE_CONTENT=false.
Messages come back with empty text. Message Content is off in the portal. Enable it; the flag alone does not change what the REST API returns.
A read fails with "lacks the Read Message History permission". Without it, Discord returns an empty list rather than an error, so the read tools report the missing permission instead of an empty channel. Grant it in the channel, or in the parent channel of a thread.
Missing Access or Missing Permissions. The bot cannot see the channel, or the target role or member sits above the bot's highest role. Check overwrites with discord_get_channel_permissions.
Finding IDs. Enable Developer Mode in Discord (Settings, Advanced), then right-click a server, channel or user and choose Copy ID.
Contributing
Contributions are welcome. CONTRIBUTING.md covers the module layout, the tool definition quality bar and the release flow. Report vulnerabilities as described in SECURITY.md.
License
MIT, see LICENSE. discord-mcp is an independent open-source project, not affiliated with or endorsed by Discord Inc.
Comma-separated toolsets to expose: discovery, messages, channels, permissions, members, roles, moderation, screening, stats, forums, webhooks, scheduled_events, invites, dm, or all. An unknown name stops the server at startup.
DISCORD_MCP_READ_ONLYdefault false
Set to true to expose only the read-only tools of the selected toolsets: write tools are neither listed nor callable. Any value other than true/false, 1/0, yes/no or on/off stops the server at startup.
DISCORD_ALLOWED_GUILDS
Comma-separated guild IDs the server may act on. Calls that target any other guild are rejected. Unset allows every guild.
DISCORD_MESSAGE_CONTENTdefault true
Set to false to stop requesting the Message Content privileged intent at connect time.
DISCORD_GUILD_MEMBERSdefault true
Set to false to stop requesting the Server Members privileged intent at connect time.
DISCORD_MCP_TRANSPORTdefault stdio
stdio, or http to serve Streamable HTTP on /mcp for remote clients such as the OpenAI Responses API, Codex or n8n. Any other value stops the server at startup.
DISCORD_MCP_HTTP_TOKENsecret
Bearer token every HTTP request must carry. Required when DISCORD_MCP_TRANSPORT is http: at least 32 characters from the RFC 6750 b64token alphabet, different from DISCORD_TOKEN. Generate one with openssl rand -hex 32.
DISCORD_MCP_HTTP_HOSTdefault 127.0.0.1
Address the HTTP server listens on when DISCORD_MCP_TRANSPORT is http. Keep 127.0.0.1 unless the server runs in a container.
DISCORD_MCP_HTTP_PORTdefault 3000
Port the HTTP server listens on when DISCORD_MCP_TRANSPORT is http.
DISCORD_MCP_HTTP_ALLOWED_HOSTS
Comma-separated hostnames, without port, accepted in the Host header of HTTP requests besides localhost, 127.0.0.1 and [::1], such as the public name a reverse proxy forwards.