discord-mcp

Troubleshooting

What each error means and how to fix it, then answers to the questions people ask first.

Connecting

The server starts without connecting to Discord. It connects on the first tool call, so these errors show up as the answer to your first prompt.

The token is missing

DISCORD_TOKEN is required. Set it in your MCP client config or a .env file.

The client started the server without DISCORD_TOKEN. Check the env of the server entry, then restart the client. With the Claude Code plugin, the server stays off until you set the token with /plugin configure discord-mcp@pasympa, and the token takes effect after a restart of Claude Code.

The token is invalid

Discord login failed: An invalid token was provided.

Discord refused the token. A token stops working when someone chooses Reset Token on the Bot page. Reset it once more, copy the new one into your config, and restart the client.

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.

A call can also stop after 30 seconds with a message that says: Check the token and that the Server Members / Message Content privileged intents are enabled in the Developer Portal.

The server stops at startup

An invalid setting stops the server before it lists any tool, with a message that names the variable:

Invalid DISCORD_MCP_TOOLSETS: unknown toolset(s) "chanels". Known: all, discovery, messages, channels, permissions, members, roles, moderation, screening, stats, forums, webhooks, scheduled_events, invites, dm.
DISCORD_MCP_READ_ONLY leaves no tool to expose: the toolsets in DISCORD_MCP_TOOLSETS ("channels") have no read-only tool. Add a toolset with read tools, such as discovery, or turn read-only mode off.

Your client then shows the server as failed, and its MCP log holds the message. The configuration reference lists the accepted values.

Every tool is listed twice

In Claude Code, the plugin and a server added with claude mcp add both run. Keep one. To drop the manual one, run claude mcp remove discord.

Discord errors

When Discord refuses a call, the server returns its code and message, then a hint, as in Discord API error 50013 (HTTP 403): Missing Permissions. followed by the hint below.

In short, for 50001 and 50013: 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 (read-only).

50013 Missing Permissions

Missing permissions; the bot lacks the permission this action requires.

Grant the permission in Server Settings, on a role the bot holds, or in the channel's overwrites. Each tool page names the permissions it needs. When the target is a role or a member, see role hierarchy.

50001 Missing Access

Missing access; the bot is not in the guild, cannot see this channel, or lacks Read Message History to fetch a single message.

Give the bot View Channel on the channel, and Read Message History to read or fetch messages. In a thread, the parent channel's permissions apply. discord_get_channel_permissions (read-only) shows the overwrites in place.

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.

The error names the channel: Without it, Discord returns no messages instead of an error.

A role or member edit fails

The bot can only edit, assign, remove or move roles below its own highest role. The same goes for nicknames, kicks, bans and timeouts: the member's highest role must sit below the bot's. Discord also refuses to time out the server owner or a member with Administrator. Drag the bot's role higher in Server Settings > Roles; the bot cannot raise its own role.

A channel is missing from the lists

Discord hides from a bot the channels it cannot view: their name reads ___hidden___ and their overwrites are replaced by a single @everyone View Channel deny. From 2026-11-16, its REST channel list also omits them. discord_list_channels (read-only) leaves them out. discord_audit_permissions (read-only) and discord_find_channel_by_name (read-only) leave them out and count them in hiddenChannels; the search adds a note:

N channel(s) are hidden from the bot and left out of matches, so a channel missing here may still exist.

discord_get_channel_permissions (read-only), discord_copy_permissions (destructive) and discord_clone_channel (write) refuse such a channel rather than act on placeholder data. Grant the bot View Channel on it.

The guild is not in the allow-list

guild_id is not in the DISCORD_ALLOWED_GUILDS allow-list.
Guild 123456789012345678 is not in the DISCORD_ALLOWED_GUILDS allow-list.

The first form answers a guild_id argument, the second a channel, thread, webhook or invite that belongs to another server. DISCORD_ALLOWED_GUILDS is set and the call targets a server outside it. Add the server's ID to the list, or check that the ID is the one you meant. Configuration covers the variable.

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.

Finding IDs

Enable Developer Mode in Discord (Settings, Advanced), then right-click a server, channel or user and choose Copy ID.

Questions

Is it safe to give an assistant my server?

The assistant acts through your bot, so it can do only what the bot's permissions allow. Mass actions such as discord_bulk_ban (destructive) preview by default. Every tool says whether it reads, writes or destroys, so your client can approve reads and ask before the rest; check how yours is set. To go further, turn on read-only mode, load fewer toolsets, and list your servers in DISCORD_ALLOWED_GUILDS. See Safety.

Can it only read?

Yes. DISCORD_MCP_READ_ONLY=true keeps the 35 read-only tools and hides the others. Two of them stay sensitive: discord_list_webhooks (read-only) returns webhook tokens, and discord_read_dms (read-only) reads the bot's direct messages. Leave webhooks and dm out of your toolsets to hide them.

Which permissions should the bot get?

The ones your tasks need. The invite link asks for every permission the tools use; untick the rest in the authorization screen. Each tool page names its own. Avoid Administrator unless a task needs it, such as pruning on a server that requires Administrator for it. Administrator ignores channel overwrites, so a mistake reaches every channel.

How much context does it use?

Every tool definition the client loads takes room in the assistant's context: about 35k tokens for the full set. DISCORD_MCP_TOOLSETS loads only what you pick. The chat assistant profile, discovery,messages, loads 25 tools for about 10k tokens. The toolset builder shows the cost of any mix.

Does it work with ChatGPT or Codex?

Codex, yes: the Codex CLI starts it like any local server, and Codex can also reach it over HTTP. The OpenAI Responses API reaches it over HTTP too. ChatGPT connectors need OAuth 2.1 or OpenAI's Secure MCP Tunnel, and the HTTP mode uses a static token, so it is not for ChatGPT. See remote clients.

Can I run it in Docker?

Yes. The image is pasympa/discord-mcp. The guide has the client config, and the HTTP section shows how to publish the port on the loopback only.

Is it made by Discord?

No. discord-mcp is an independent open-source project under the MIT license, not affiliated with or endorsed by Discord Inc.