Diagnose a broken connection with one command

discord-mcp doctor --online

Exit 0 means every check passed, 1 means warnings only, 2 means at least one failure.

The CLI won't install or start#

Run node --version. discord-mcp requires Node.js 22.12 or newer. After upgrading, reinstall and verify:

npm install -g @discord-mcp/cli
discord-mcp --version

For a one-off check without a global install:

npx --yes @discord-mcp/cli@latest doctor --online

DISCORD_TOKEN is missing or invalid#

doctor reads the environment of the terminal where it runs, it does not read the token back out of your MCP client config. Make DISCORD_TOKEN available to the environment that launches the client.

• If a stateless init config still shows the literal ${env:DISCORD_TOKEN}, replace it with the real value unless you've verified your client expands environment placeholders itself.
• A Bot prefix is accepted but not required.
• Discord returning 401 means the token is wrong, reset it in the Developer Portal and replace the old value everywhere it's used.
• A bot-identity mismatch at startup means your token doesn't match DISCORD_EXPECTED_BOT_ID, restore the correct token rather than changing the expected ID just to make the server start.

For a saved profile, run discord-mcp profile show <name> and discord-mcp doctor --profile <name> --online together to inspect the non-secret boundary and the live token check side by side. Treat the generated client config as a secret once it holds a token, never commit, share, or screenshot it.

Your client doesn't show discord-mcp at all#

• Confirm the discord-mcp entry sits inside the client's top-level mcpServers object.
• Keep any existing MCP entries when you merge in the generated snippet.
• Check that the generated command and first args path still exist, the snippet is tied to the exact CLI install that created it, regenerate it after moving or reinstalling Node.
• Fully quit and reopen the client, then check its MCP or server logs.

You changed the token, profile, or version but nothing changed#

The MCP server is a child process of your client. It reads the current profile, pinned package, and inherited environment only when that child starts.

• Run discord-mcp profile show <name> to confirm the saved bot, guild allowlist, client, and tool surface.
• Confirm DISCORD_TOKEN is available to the environment that will launch the client, a passing doctor in a different terminal only proves that terminal's environment.
• Fully quit and reopen the client, a window reload can keep the old parent or MCP child alive.
• Run discord-mcp doctor --profile <name> --online from the intended launch environment and compare its redacted result with the client logs.

A tool returns 403 Missing Permissions#

Your bot is authenticated, but its Discord role can't perform that action in that channel. Check both the server-wide role and any channel-specific permission overrides, then grant the smallest permission the tool needs and retry.

A tool returns 404 or "Unknown Channel"#

Discord tools use snowflake IDs, not #channel-name. Enable Developer Mode, copy the server or channel ID directly, or call channels_list with the right guild_id and use the returned channel ID.

A write happened without a confirmation prompt#

This can be expected. Only tools whose reference page says Confirmation required use the __confirm plus MCP_DRY_RUN gate, see how it works for the full list. Ordinary writes such as messages_send are not gated and can execute on the first call. Limit your bot's Discord permissions and keep testing in a private server.

DRY_RUN_PREVIEW never becomes a real mutation#

For a confirmation-gated tool, both conditions are required: MCP_DRY_RUN=false in the server environment, and __confirm: true on the call itself. The setting doesn't affect tools that aren't confirmation-gated at all.

Gateway mode falls back to REST-only#

Gateway support requires discord.js to be resolvable from the same install as the CLI. If Gateway startup fails, discord-mcp logs a warning and continues in REST-only mode rather than crashing.

npm install -g @discord-mcp/cli discord.js
discord-mcp serve --gateway

Reinstall both together, check the requested intents in the Developer Portal, then restart your client.

Still blocked?#

Open a GitHub issue with your CLI version, Node version, operating system, client name, and redacted error output. Never include the bot token or a client config that contains it.

Next steps#

Back to the quickstart if you're still setting up, or the overview for everything else.