Send your first verified message in under 15 minutes

What you'll set up#

A Discord bot installed in a private test server, with its token, guild ID, and channel ID ready.
The @discord-mcp/cli package installed globally.
Your MCP client (Claude Desktop, Claude Code, Codex, Cursor, or a generic client) configured to launch discord-mcp.
A confirmed read-only Discord request, followed by one test message.

Before you begin, confirm you have a private Discord server where you can safely test a bot, and a place outside source control to store the bot token.

Step 1: create a Discord bot#

Open the Discord Developer Portal, select New Application, and create it. New applications include a bot user by default.
Open Bot, select Reset Token, and copy the token into a password manager. Discord shows it only once. Never paste it into chat, an issue, a screenshot, or a committed file, if it leaks, reset it immediately.
Open Installation, configure a Guild Install with the bot scope, and grant only View Channels and Send Messages for now. Add moderation, role, webhook, or thread permissions later, only when a workflow needs them. Do not grant Administrator as a shortcut.
Copy the install link, open it, choose Add to server, and select your test server.
In Discord, open User Settings → Advanced and enable Developer Mode. Right-click your test server for Copy Server ID (guild_id) and right-click your test channel for Copy Channel ID (channel_id).

The default setup uses Discord's HTTP API and needs no privileged Gateway intents. Only enable Gateway mode later if you need live event notifications.

Step 2: install the CLI#

discord-mcp requires Node.js 22.12 or newer. Check with node --version.

npm install -g @discord-mcp/cli
# or: pnpm add -g @discord-mcp/cli
# or: yarn global add @discord-mcp/cli

Verify with discord-mcp --version (a global flag, there is no version subcommand - an unrecognized first argument falls through to serve and boots a stdio server waiting on stdin).

Optionally validate the installed package before connecting a bot at all:

discord-mcp catalog --check

This needs no Discord token and performs no Discord request. It confirms the installed package exposes the real 208-tool catalog.

Step 3: connect your MCP client#

Run discord-mcp init to print a config snippet for your client, or discord-mcp setup --profile devbot --client <name> to save a named profile (claude-desktop, claude-code, codex, cursor, or generic):

discord-mcp setup --profile devbot --client claude-desktop

Merge the generated discord-mcp entry into your client's existing MCP server config rather than replacing the whole file, then restart the client fully so the child process picks up the new environment.

Step 4: prove the connection read-only#

Validate the token against Discord from a terminal, without putting it in your shell history permanently:

read -rsp 'Discord bot token: ' DISCORD_TOKEN && printf '\n'
export DISCORD_TOKEN
discord-mcp doctor --profile devbot --online
unset DISCORD_TOKEN

Look for the token-online row reporting OK and Discord accepted token. Then, in your MCP client, ask it to call the bot-identity tool and report the result, without invoking anything else. A successful result identifies the same bot you created in Step 1.

Step 5: send one test message#

Ask your client to look up the channel ID for your test channel, then send one message to it. A successful messages_send result contains message_id, channel_id, jump_url, and timestamp. Open jump_url to confirm the message landed in Discord.

messages_send is a write, but it is not destructive and is not confirmation-gated, it executes on the first call. Keep onboarding inside a test server and grant the bot only the permissions it needs.

Checklist before you move on#

discord-mcp --version prints the installed version.
discord-mcp doctor --online reports the token check as OK.
Your client returned your bot's own username and ID from a read-only call.
You opened jump_url and saw the test message in Discord.

Next steps#

Ready for a full guild build with review and independent verification: get your first verified Discord outcome. Hit a snag: troubleshooting covers the common failure modes. Want the exact schema for every tool: browse tools by category. Back to the overview.

Updated Aug 14, 2026