Troubleshooting

Start with one command:

discord-mcp doctor --online

Exit 0 means every check passed, 1 means warnings only, and 2 means at least one failure. Use the symptom below that matches what you see.

The CLI will not install or start

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

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

For a one-off diagnostic without a global install, use the scoped package name:

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

DISCORD_TOKEN is missing or invalid

• A profile-based setup snippet intentionally omits the token from JSON clients; make DISCORD_TOKEN available to the client process before it launches the MCP child.
• If a stateless init config still contains the literal ${env:DISCORD_TOKEN}, replace that placeholder with the real token in the local client config unless you have verified that your client expands environment placeholders.
• doctor reads the environment of the terminal where it runs; it does not read the token back from your MCP client config.
• A Bot prefix is accepted but not required.
• If Discord returns 401, reset the token in the Developer Portal and replace the old value.
• If startup reports a bot identity mismatch, restore the token for DISCORD_EXPECTED_BOT_ID; do not replace the expected ID merely to make the server start. Follow the credential lifecycle guide.
• For a saved profile, run discord-mcp profile show <name> and discord-mcp doctor --profile <name> --online to inspect the non-secret boundary and verify its current environment token together.

Danger

Treat the generated client configuration as a secret once it contains a token. Never commit, share, or screenshot it.

The client does not show discord-mcp

1. Confirm that the discord-mcp entry is inside the client’s top-level mcpServers object.
2. Keep existing MCP entries when merging the generated snippet.
3. Check that the generated command and first args path still exist. The snippet is tied to the CLI installation that created it; regenerate it after moving or reinstalling Node.
4. Fully quit and reopen the client, then inspect its MCP/server logs.

I see many discord-mcp processes

Each active MCP client session owns its own stdio child. Several open sessions therefore legitimately produce several server processes; discord-mcp does not use a global singleton because sessions can carry different profiles, environment, and tool boundaries.

On Windows, a PowerShell launch through npx can add additional npm/cmd/PowerShell wrapper processes that remain for the server’s lifetime. Use the generated launcher first, then inspect the client process tree before terminating anything. A direct Node installation and launcher avoids those package-manager wrappers. It does not merge separate client sessions into one process.

When a client closes its stdio pipe, the server starts one deduplicated cleanup for that child and releases its resources before exiting; cleanup is bounded to five seconds. If a child remains after the host is fully closed, capture the client name, CLI version, Node version, and redacted process-tree output, then restart that client once. Do not kill another session that is still in use.

I changed the token, profile, config, or version but nothing changed

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

1. Run discord-mcp profile show <name> to confirm the saved bot, guild allowlist, client, and tool surface.
2. Make DISCORD_TOKEN available to the environment that will launch the MCP client. A passing doctor in another terminal proves only that terminal’s environment.
3. Fully quit and reopen the client. A window reload may keep the old parent or MCP child alive.
4. If startup still fails, 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

The bot is authenticated but its Discord role cannot perform the action in that channel. Check both the server role and channel-specific permission overrides. Grant the smallest permission required by the tool, then retry.

A tool returns 404 or “Unknown Channel”

Discord tools use snowflake IDs, not #channel names. Enable Developer Mode and copy the server or channel ID, or call channels_list with the correct 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. Ordinary writes such as messages_send are not gated and can execute on the first call. Limit the bot’s Discord permissions and use a test server.

DRY_RUN_PREVIEW never becomes a real mutation

For a confirmation-gated tool, both conditions are required:

1. set MCP_DRY_RUN=false in the server’s environment; and
2. send the tool call with __confirm: true.

The setting does not affect tools that are not confirmation-gated.

Gateway mode falls back to REST-only

Gateway support requires discord.js to be resolvable from the CLI installation. If Gateway startup fails, discord-mcp logs a warning and continues in REST-only mode. Reinstall the CLI and discord.js together, check the requested intents, then restart the client.

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

Gateway subscriptions are an advanced notification surface; they are not a replacement for the REST tool and resource catalogs.

Still blocked?

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