discord-server-mcp

Create, organise and moderate Discord servers from Claude (or any MCP client) through your own bot.

Ask in plain words: "set up a server for my gaming group", "add a Solved tag to the help forum", "post this announcement with the image and ping @Announcements", "who can see #staff-chat?". The assistant reads the server, shows you the plan, and acts once you agree.

• 132 tools, of which only a core of 48 is on at first; the rest turn on when a task needs them, plus discord_api for any other Discord endpoint.

• Live events: the assistant sees what happens as it happens: new messages, mentions of the bot, members joining or leaving, reactions and button clicks. It can also wait for something, such as a reply.

• Automations:

  • role menus with buttons, a dropdown or reactions;

  • welcome messages with auto-roles, and verification with an "I accept the rules" button;

  • numbered support tickets in private channels; a staff-only channel gets a line when each one opens (with a Claim button), is claimed and closes (with a summary and the full transcript), and ticket_history finds any past ticket;

  • support forums: new posts get an Open tag and a Solved button, staff can claim them, solved posts close, idle ones close after a few days;

  • the server's own slash commands, such as /rules or /links;

  • rules, "when this happens, do that": answer words, delete links, give a role on a reaction, DM new members, time out spammers;

  • scheduled and recurring messages, in any time zone;

  • moderation logs, in one channel, split by kind, or in a forum with one post per member and tags per kind (filter by member, kind or both): deleted and edited messages with what they said, joins and leaves, kicks, bans, timeouts, nickname and role changes with who did it and why, AutoMod blocks. The bot's own automations and ticket channels are left out, and every entry is kept for search_mod_log and /modlog;

  • staff alerts: a role ping in a staff channel and/or DMs on bans, kicks, timeouts, AutoMod blocks and raids;

  • staff slash commands inside Discord: /lock, /unlock, /slowmode, /purge, /timeout, /untimeout, /kick, /ban, /unban, /role add|remove, /announce, /ticket close|claim, /modlog. Discord shows each one only to members with the matching permission, they respect the role order, and the log shows who used them.

  Members see these texts in the server's language: English, Portuguese (Portugal and Brazil), Spanish, French, German, Italian, Russian, Japanese, Chinese (simplified), Korean, Polish or Turkish. Every text can be changed, then or later, so any other language works too. Staff command names can be in English, translated for each member, or in one language for everyone. They run while the assistant is open, or around the clock with discord-server-mcp run or Docker.

• Background jobs: big builds, role changes for many members, message backups (JSON, Markdown and HTML transcripts) and restores. Each job shows its progress and can be cancelled or resumed.

• Local or remote: stdio for desktop apps, or Streamable HTTP with a bearer token (serve --http).

• Guided from zero: /discord finds what is already set up, lets you pick a server, and walks you through creating a bot, adding it to an existing server, or creating a brand-new server. The new server gets built step by step: questions, plan, structure, rules and welcome texts, then Community, onboarding and AutoMod.

• Several bots and servers:

  • add as many bots as you like and move between their servers;

  • each request uses the bot that is in that server, or the one you chose for it;

  • every result says which bot acted.

• Warns about 2FA: when a server requires two-factor authentication for moderation, it says who needs 2FA and why.

• Templates, layouts and backups: build a whole server from a template, a layout you describe, or a backup. Only what is missing is created, and an interrupted build can be resumed.

• Safe by design:

  • every change can be previewed (dry_run);

  • permanent actions need confirm: true;

  • there are read-only and preview-only modes, an allow-list of servers and selectable tool packs;

  • nobody is pinged unless you ask.

• Built for Claude: a /discord command with a menu and a guided setup, and skills that make Claude show the plan before acting.

• Easy install:

  • one-click extension for Claude Desktop (asks for the token in a form);

  • a plugin for Claude Code;

  • a setup command (init) for every other client.

• Names, not ids: announcements, @Moderator, alice. Emoji prefixes are ignored when matching, and typos get "did you mean…?" suggestions.

• Files and images from your computer or the web, inside messages and embeds, and as icons, emojis and banners.

• Online presence: the bot shows as online with your status text while it runs.

Install

1. Create the bot (2 minutes)

1. Go to discord.com/developers/applications, click New Application, open Bot and click Reset Token. Copy the token and keep it secret: it controls the bot.

2. Optional: on the same page, turn on Server Members Intent so member lists and role member counts work.

3. Add the bot to your server: OAuth2 → URL Generator → scope bot → permission Administrator → open the link. The /discord command and the init command also give you this link.

4. In Server Settings → Roles, drag the bot's role near the top. A bot can only manage roles and members below its own highest role.

2. Add it to your app

Claude Desktop: download discord-server-mcp-<version>.mcpb from the latest release and double-click it. Claude Desktop shows a form; paste the token there. Node.js is not needed because Claude Desktop includes it.

Claude Code:

/plugin install discord-server --marketplace pr5ias/discord-server-mcp

Then run /discord: Claude walks you through creating the bot and asks for the token in a private box, or, if your app has none, on a one-time page in your browser at 127.0.0.1. The token goes straight to the server and is saved in ~/.discord-mcp/bots.json, never into the chat. On older versions, run /plugin marketplace add pr5ias/discord-server-mcp first, then /plugin install discord-server@discord-server-mcp. The same .plugin file from the releases also installs in the Claude app.

Cursor, Windsurf, VS Code and other MCP clients (needs Node.js 22+):

npx discord-server-mcp init

Without npm, clone this repository and run node dist/index.mjs init instead.

The wizard checks the token, saves it to ~/.discord-mcp/bots.json (run it again to add more bots), prints the invite link, and adds the server to Claude Desktop, Claude Code, Cursor and Windsurf if you want. To set it up by hand, start the server with npx -y discord-server-mcp and give it the token as DISCORD_BOT_TOKEN.

3. Use it

Restart the app and type /discord (in Claude), or just ask "show my Discord server". If something is off, /discord setup or node dist/index.mjs check tells you exactly what to fix.

Related MCP server: discord-mcp

The /discord command

• /discord shows what is set up and asks which server to work on, or offers to add a bot, add it to another server, or create a new server. With no bot yet it explains how bots work and walks you through creating one. After you pick a server, a menu opens:

  • Check-up: finds problems, such as missing topics, empty channels, risky roles or a bot role that is too low.

  • Build or reorganise: templates, layouts and restores.

  • Messages & announcements.

  • Roles, members & moderation.

• Build or reorganise includes Build a server from scratch:

  1. Questions about the server: what it is for, languages, which areas, size.

  2. A starting point: a built-in template, a template from the internet, a copy of another of your servers, or your own description. It is adapted to your answers, then a preview: the channel sidebar as members will see it, the roles, and a grid of who can see and write where. Approve it, ask for changes, or try another template, as many times as you like.

  3. The structure: roles, channels and permissions.

  4. The rules, welcome, FAQ and first announcement, written for you to approve before they are posted.

  5. Optional settings: Community, onboarding, the welcome screen, verification, AutoMod and an invite link.

• /discord setup walks through the setup one step at a time.

• /discord <request> skips the menu, e.g. /discord build the project template.

Tools

132 tools in packs. Only the core pack (48 tools) is on at first, so the model has fewer tools to choose from and each request stays small. When a task needs more, the assistant calls enable_tools and the pack appears at once. In apps that do not refresh their tool list, the assistant calls the same tools through use_tool, so nothing is out of reach. DISCORD_TOOLSETS=all turns everything on.

Templates and backups

preview_blueprint and apply_blueprint accept any of these:

• a built-in template: community, gaming, creator, project or study. They follow the structure most servers use: an information area with welcome, rules and announcements, community chat, topic or support areas, voice, and a private staff area.

• a Discord template from the internet (discord_template: a discord.new/… link from a site such as discords.com/templates);

• another server the bot is in (copy_from_server);

• a JSON file from export_server_structure;

• a layout written on the spot:

{
  "roles": [{ "name": "Event Host", "color": "#e67e22" }],
  "categories": [{
    "name": "Events",
    "channels": [
      { "name": "📅-event-announcements", "type": "announcement", "topic": "Upcoming events",
        "overrides": [{ "target": "@everyone", "deny": ["SendMessages"] }, { "target": "Event Host", "allow": ["SendMessages"] }] },
      { "name": "💬-event-chat", "type": "text", "topic": "Talk about the events" },
      { "name": "🎙️-event-stage", "type": "stage" }
    ]
  }]
}

• mode: "plan" lists the steps and changes nothing. mode: "apply" carries them out.

• Existing roles, categories and channels are matched by name, with emojis and dashes ignored, and are reused.

• Missing forum tags and topics are added.

• Nothing is ever deleted.

• With update_existing: true it also moves channels into place, updates roles that differ, and reorders everything.

Running around the clock and remotely

Role menus, welcomes, tickets, slash commands and the moderation log need a bot that is online. The MCP server keeps the bots online while your AI app is open. To keep them working all the time, run this on a computer or server that stays on:

node dist/index.mjs run        # or: npx discord-server-mcp run

Or with Docker. Settings, bots and automations are kept in the /data volume. Copy ~/.discord-mcp/automations.json into it to bring over what you set up in Claude.

docker build -t discord-server-mcp .
docker run -d --restart unless-stopped --name discord-bot \
  -v discord-data:/data -e DISCORD_BOT_TOKEN=<token> discord-server-mcp

Add serve --http --host 0.0.0.0 at the end, -p 3333:3333 and -e DISCORD_MCP_HTTP_TOKEN=<secret> to serve the MCP tools over HTTP from the container instead.

To use the tools from another machine, serve MCP over HTTP:

DISCORD_MCP_HTTP_TOKEN=<long random secret> node dist/index.mjs serve --http --port 3333

• Endpoint: clients connect to http://<host>:3333/mcp and send Authorization: Bearer <secret>.

• Who can reach it: it listens on 127.0.0.1 only. Add --host 0.0.0.0 and put HTTPS in front to reach it from elsewhere.

• Health check: /health reports the version and whether each bot is connected.

Intents. For message text (and the text of deleted messages in the moderation log) and member join events, open the Developer Portal → Bot and turn on Message Content and Server Members. Without them the live features still work, but message text comes through empty and joins are not seen. events_status shows which intents are active.

Safety settings

Just ask Claude ("only show changes, don't apply them", "set the bot's status to My Server"): the configure tool saves them in ~/.discord-mcp/settings.json. The Claude Desktop extension also asks for the main ones during install. Environment variables with the same names override the file.

Tools carry MCP annotations (read-only, destructive), so clients can ask before running them. Audit-log reasons are supported on moderation tools.

Sharing a bot

Two people can use the same bot from their own computers. Each one adds the same token with add_bot.

• Share it through a Team: in the Developer Portal, go to Teams → New Team, invite the person, then open the app's General Information and click Transfer App to Team. Don't send the token in a chat.

• Resetting the token affects everyone: a reset gives a new token, so agree before doing it.

• The audit log can't tell you apart: every change shows as the bot. If you need to know who did what, give each person their own bot.

When several bots are in one server, every result says which bot acted, set_server_bot chooses the bot for that server, and any request can pass bot.

Limits

• New servers: Discord rarely lets bots create servers. Create the server in the app, invite the bot, then build it with a template.

• Role order: a bot cannot manage roles or members at or above its own highest role.

• Other bots' messages cannot be edited. Re-post them and delete the old ones.

• Always-on features: role menus, welcomes, tickets, slash commands and the moderation log work only while the server runs. Use run or Docker on an always-on machine to keep them working all the time. Slash commands answer with fixed texts; they do not run other actions.

• Bulk delete only works on messages younger than 14 days. Older ones are deleted one by one.

• Message search scans recent messages per channel, because Discord's search API is not available to bots.

• Your own account is never used. Automating a personal account (a "selfbot") breaks Discord's terms and can get the account banned.

Publishing (maintainers)

For a new version, raise the version in package.json, server.json, .claude-plugin/plugin.json and src/version.js, then:

npm test                         # builds and runs every test against the fake Discord API
npm run package                  # release/: the .mcpb and .plugin files
npm login                        # opens the browser; npm needs 2FA on the account
npm publish                      # staged: the version waits until it is approved

npm now stages publishes: the new version stays hidden (a first publish shows a 0.0.0-stage placeholder) until a maintainer approves it in npmjs.com → Staged Packages → Approve, or with npm stage approve <id>, with 2FA. Then:

mcp-publisher login github       # https://github.com/modelcontextprotocol/registry
mcp-publisher publish            # lists server.json in the official MCP registry

Finally, make a GitHub release tagged v<version> with the two files from release/.

Development

npm install
npm test          # builds, then runs every tool pack against a fake Discord API
npm run package   # release/: the .mcpb extension and the .plugin file

• Source: src/, plain JavaScript ES modules.

  • discord.js: REST client, lookups and dry runs.

  • tool.js: write modes and tool packs.

  • tools/*.js: the tools.

  • templates.js: server templates.

  • cli.js: init and check.

• Build: dist/index.mjs is the bundled server and is committed, so the plugin works straight from the repository.

• Releases: run npm test and npm run package, then attach the two files from release/ to a GitHub release tagged v<version>.

License

MIT