Discord MCP Server: Bot Setup & Recipes (2026 Guide)

TL;DR + what you actually need

Four things stand between you and an agent that runs your Discord server:

• One secret: DISCORD_TOKEN — a bot token from the Discord Developer Portal. Not your account password, not a user token. Bot token only.
• Two intents: toggle Server Members Intent and Message Content Intent under your app’s Bot settings. These are privileged — off by default, and the server fails at startup without them.
• One invite: generate an OAuth2 URL with the bot and applications.commands scopes plus the permissions you want the agent to have, open it, and add the bot to your server.
• One process: the canonical discord-agent-mcp server (MIT, TypeScript, Node 20+). Clone, build, run — it serves MCP over HTTP at localhost:3000/mcp, with a stdio mode for clients that need it.

The copy-paste version, end to end:

git clone https://github.com/aj-geddes/discord-agent-mcp.git
cd discord-agent-mcp
npm install
cp .env.example .env   # paste your DISCORD_TOKEN
npm run build
npm start              # → http://localhost:3000/mcp

# then, in another terminal:
claude mcp add --transport http discord-agent http://localhost:3000/mcp

The rest of this guide explains why each step exists, what the 71 tools actually do, and where Discord’s own rules — intents, role hierarchy, rate limits — shape what your agent can and cannot pull off.

What Discord MCP servers do

A Discord MCP server is a process that logs into Discord as a bot (via Discord.js or a similar library) and exposes the bot’s capabilities as MCP tools. Your agent calls read_messages; the server fetches channel history through Discord’s API and returns it as a tool response the model can reason over. The agent calls timeout_member; a user gets muted for an hour. The bot is the hands; the model is the judgment.

That covers three distinct job families, and it’s worth being explicit about which one you’re hiring for:

• Reading: pull message history, list members, find forum threads, read audit logs. This is what powers community digests and support-thread mining — the agent as analyst.
• Writing: send and edit messages, post rich embeds, create channels and roles, schedule events. The agent as community manager.
• Moderating: kick, ban, timeout, bulk-delete, configure auto-mod rules. The agent as triage assistant — and the family where you want a human approving every call.

One boundary to set expectations early: everything here rides Discord’s sanctioned bot API. The bot sees only servers it’s invited to and channels its role can view. It cannot read your personal DMs or lurk in servers you browse as a user. And the inverse rule matters more: automating a user account (a “self-bot”) is explicitly forbidden — Discord’s support docs say automation outside the OAuth2/bot API can result in account termination. Every server covered in this guide uses a proper bot token, so you’re on the right side of that line. (Telegram’s ecosystem, by contrast, has both bot-API and user-session MCP servers — see our Telegram MCP guide for how differently that trust model plays out.)

The canonical entry in our catalog is /servers/discord — the discord-agent-mcp server by aj-geddes: 71 tools across twelve categories, TypeScript with Zod validation, automatic reconnection, structured JSON logging, and Docker/Kubernetes deployment manifests in the repo. It’s the implementation every snippet below assumes; alternatives get their own section near the end.

Auth: bot token, intents, permissions

Discord auth for MCP is a three-layer stack, and each layer fails differently. Token problems fail loudly at login. Intent problems kill the gateway connection. Permission problems fail quietly, per-channel, at tool time. Walk through them in order.

Layer 1 — the bot token

Create an application at discord.com/developers/applications (New Application, name it, create). Open the Bot section and click Reset Token. The token is shown once — copy it now, store it like a password. This is the only credential the MCP server needs:

# .env
DISCORD_TOKEN=your_bot_token_here
TRANSPORT_MODE=http   # or "stdio"
HTTP_PORT=3000
LOG_LEVEL=info

Anyone holding the token is the bot, with every permission the bot has in every server it’s in. Keep it in .env (gitignored), rotate it if it ever touches a paste or a screenshot, and never embed it in a config file you commit.

Layer 2 — privileged gateway intents

Intents are subscription flags a bot declares when it connects: which event categories Discord should send it. Three are privileged because they expose sensitive data — GUILD_MEMBERS, GUILD_PRESENCES, and MESSAGE_CONTENT — and they’re off until you toggle them in the portal. The discord-agent-mcp docs require two:

• Server Members Intent — “Required for member management”: listing members, nicknames, role assignment.
• Message Content Intent — “Required for reading messages”: without it, read_messages gets events with hollow content.

Toggle both under Bot → Privileged Gateway Intents and save. If the server requests an intent you didn’t enable, Discord closes the gateway with close code 4014 (Disallowed intents) — the MCP server dies at startup and your client reports no tools. One scaling note from Discord’s gateway docs: once an app passes 10,000 unique users across its servers, continued access to privileged intents requires a review. For a personal or team server you’ll never hit it; for a bot you distribute, plan for the verification step.

Layer 3 — permissions and role hierarchy

The invite URL decides what the bot may do inside your server. In OAuth2 → URL Generator, select the bot and applications.commands scopes, then either Administrator (full access, fine for a private test server) or the specific set the project docs list: Manage Channels, Manage Roles, Manage Messages, Read Messages/View Channels, Send Messages, Manage Threads, Moderate Members. Open the generated URL, pick your server, authorize.

Two rules that aren’t obvious until they burn you. First, role position beats permission flags: a bot can only manage roles and members that sit below its own highest role in the server’s role list. A bot with Manage Roles still gets Missing Permissions trying to assign a role positioned above it — drag the bot’s role up in Server Settings. Second, channel overrides beat server permissions: a channel that denies View Channel to the bot’s role is invisible to every read tool, no error raised. That’s a feature — it’s exactly how you keep the agent out of sensitive channels.

Install (every client)

Unlike most MCP servers in the catalog, discord-agent-mcp is not published to npm — the documented install is from source, and the server runs as a persistent process (it holds a live gateway connection to Discord, so a spawn-per-session model fits it less well than a long-running one). The install card below mirrors the canonical /servers/discord entry; the verified from-source path is the five commands from the TL;DR.

One-line install · Discord

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-by-client notes:

• Claude Code — first-class path, via streamable HTTP: claude mcp add --transport http discord-agent http://localhost:3000/mcp. Run claude mcp list to confirm registration. Full flag reference at /clients/claude-code.
• Claude Desktop / stdio-only clients — set TRANSPORT_MODE=stdio and point the client at the built entrypoint:

  {
    "mcpServers": {
      "discord-agent": {
        "command": "node",
        "args": ["/absolute/path/to/discord-agent-mcp/dist/index.js"],
        "env": {
          "DISCORD_TOKEN": "your_bot_token_here",
          "TRANSPORT_MODE": "stdio"
        }
      }
    }
  }

• Cursor / Windsurf / VS Code — same choice: paste the stdio JSON above into the client’s mcp.json, or register the HTTP endpoint if the client supports remote servers (most 2026 builds do).
• Docker — for an always-on bot, skip the local Node process entirely: docker run -d -p 3000:3000 -e DISCORD_TOKEN=your_token discord-mcp-server:latest after a docker build from the repo. The repo also ships Kubernetes manifests under k8s/ if your agent infrastructure already lives in a cluster.

Sanity check before blaming the client: hit http://localhost:3000/mcp only after npm start reports the bot logged in. If the Discord login fails (bad token, missing intents), there is no MCP endpoint to connect to — fix the bottom of the stack first.

Tools walkthrough (71 tools, twelve groups)

The full reference lives in the project docs; here’s the map with the tools agents actually reach for.

Messaging (10 tools)

send_message, send_rich_message (embeds), send_message_with_file, read_messages, edit_message, delete_message, bulk_delete_messages, add_reaction, pin_message, unpin_message. The workhorses are read_messages for anything analytical and send_rich_message for anything a human will read — embeds beat walls of plain text in announcement channels.

Channels (10) + threads (3)

Create text, voice, category, forum, and stage channels; modify_channel, delete_channel, and set_channel_permissions for overrides. The thread trio — find_threads, create_thread, archive_thread — is what makes forum-channel support workflows possible (Recipe 5).

Server, members, roles (17)

get_server_info, get_audit_logs, webhook and invite management on the server side; list_members, get_member_info, set_nickname for members; full CRUD plus assign_role / remove_role for roles. get_audit_logs is the underrated one — it’s the data source for moderation triage.

Moderation (6) + auto-mod (5)

kick_member, ban_member, unban_member, timeout_member, remove_timeout, get_bans — plus five tools for Discord’s native AutoMod rules (keyword filters, spam blocking) so the agent can configure moderation that runs even when the agent doesn’t. Everything in this group is side-effectful; keep it behind your client’s tool-approval prompt.

Events, emojis, stickers, commands (20)

Six scheduled-event tools (create_scheduled_event through get_event_users), four each for custom emojis and stickers, and six for registering slash commands — the last group matters if your bot doubles as a regular Discord bot with /commands beyond MCP.

Recipes

Six workflows that justify the setup. Each assumes the server is registered and the bot has the permissions from the auth section.

Recipe 1 — Scaffold a community server from one prompt

The repo’s own headline demo, and it holds up: “Create a gaming community server with voice channels for different games, a welcome channel, and moderator roles.” The agent chains create_category, create_text_channel, create_voice_channel, create_role, and set_channel_permissions. Twenty minutes of clicking becomes one reviewed plan. Ask for the structure as a list first, approve, then let it execute.

Recipe 2 — Daily community digest

Prompt: “Read the last 24 hours of #general, #support, and #showcase (read_messages). Summarize the three most active discussions, any unanswered questions, and anything that needs a moderator. Post the digest as an embed in #mod-room (send_rich_message).” Pair it with a scheduled agent run and the moderators start each day with a briefing instead of a scrollback marathon. Keep the read window tight — 100 messages per call is the practical unit.

Recipe 3 — Moderation triage (human in the loop)

Prompt: “Pull the audit log for the last 12 hours (get_audit_logs) and the last 200 messages from #general. Flag accounts with repeated link spam or slur-adjacent content. For each, propose an action — timeout_member with duration, or just a warning — and wait for my approval before calling anything.” The agent proposes; you approve; the tool fires. The phrase “Timeout user 123456789 for 1 hour for spam” from the project README is exactly the shape of command this produces. Never wire moderation tools to auto-approve — a false positive here is a community member banned by a language model.

Recipe 4 — Announcement drafting in your house style

Prompt: “Read the last ten posts in #announcements. Draft the v2.4 release announcement in the same voice and embed format, covering these three changes: … Show me the draft; on approval post it with send_rich_message and pin it.” The read-first step is what makes the output land — the agent mimics your emoji conventions, section ordering, and tone instead of producing generic changelog prose.

Recipe 5 — Support-thread mining

If support runs through a forum channel: “Use find_threads on #help. Read the 30 most recent threads. Cluster them by root cause, list the top five recurring issues with thread links, and flag threads that got zero replies.” Output feeds your FAQ, your docs backlog, and your “we keep getting this question, fix the onboarding” argument. This is the recipe that converts a noisy Discord into product signal.

Recipe 6 — Event night, end to end

“Create a voice event called ‘Game Night’ for Saturday at 8 PM (create_scheduled_event), announce it in #events with an embed, and add a 🎮 reaction for RSVPs.” Later, get_event_users tells you who’s interested. Scheduled events + announcement + reaction is three tools and one sentence.

Rate limits + intent gotchas

The MCP server is a thin adapter; every limit is Discord’s. Three numbers from the rate-limit docs worth memorizing:

• 50 requests/second global per bot, across all endpoints, on top of per-route limits tracked via X-RateLimit-* headers. Exceeding either returns 429 with a retry_after value in seconds.
• 10,000 invalid requests per 10 minutes (401s, 403s, 429s) gets your IP temporarily banned at the Cloudflare layer. A misconfigured agent looping on a permission error can hit this — the failure mode is “everything Discord stopped working from this machine,” not just the bot.
• Per-resource buckets: limits are computed per channel/guild/webhook, so hammering one channel throttles before the same volume spread across ten would.

What we got wrong the first time: we let an agent “clean up” a channel with delete_message in a loop instead of bulk_delete_messages. Per-message deletes burn one request each and the route’s bucket drains fast; the bulk tool does up to 100 in one call (Discord-side restriction: only messages younger than two weeks). The general lesson transfers: prefer the batch tool, tell the agent in your prompt to batch reads and never retry 429s in a tight loop — Discord.js handles retry_after waits, but an agent that re-issues the tool call on failure stacks requests on top of the library’s queue.

The intent gotchas cluster into two patterns. Pattern one: 4014 at startup — privileged intent requested but not toggled in the portal; the connection dies before any tool registers. Pattern two: connected but blind — Message Content intent off, bot shows online, read_messages returns messages with empty text. The second one wastes an afternoon because nothing errors; the agent shrugs and summarizes silence. Check the portal toggles before checking anything else.

Cost: zero on the Discord side — the bot API is free at any volume a community server produces. Your cost is model tokens: read_messages on a busy channel returns a lot of text, and a 24-hour digest across five channels can be six figures of input tokens. Scope the reads, summarize incrementally, and the recipes above stay cheap.

Troubleshooting

Alternatives

The catalog tracks several Discord implementations, and the right one depends on how much surface you want:

• @iqai/mcp-discord — npx-installable (npx @iqai/mcp-discord), stdio by default, 30+ tools. Distinctive: forum support with tags, and a sampling-based mode where the bot auto-responds when mentioned — closer to “AI community member” than “admin console.” Smaller surface, zero build step.
• Anthropic’s official Discord plugin (claude-plugins-official) — built for Claude Code’s channels feature: reply, react, edit_message, fetch_messages, download_attachment. It’s a message bridge (drive Claude Code from your phone via a Discord channel), not a server-management surface. Install with /plugin install discord@claude-plugins-official.
• Different platform entirely — if your community lives elsewhere, the same agent-in-the-chat pattern exists for Telegram and Slack. Telegram’s bot API is even more permissive (no privileged-intent step); Slack’s servers leans workspace-search rather than moderation. Our Telegram MCP guide covers the closest sibling, and the broader awesome MCP servers roundup maps the rest of the messaging cluster.

One contrarian note worth sitting with before you wire an agent into a work-adjacent Discord. A thread on r/soc2 from a security engineer at a SOC 2 Type 2 company raises the right question about the Claude Code channels pattern: your code stays local, but the agent’s responses — tool results, task output, status updates — transit Discord’s servers on the way to your phone. That makes Discord a de facto sub-processor for whatever the agent says out loud. For a gaming community, irrelevant. For a company server where the agent summarizes internal discussions, it’s a real data-flow question your compliance person will eventually ask. Decide what the bot is allowed to say in-channel, not just what it’s allowed to do.

FAQ

Sources

• Canonical implementation: github.com/aj-geddes/discord-agent-mcp (MIT) and its docs site: aj-geddes.github.io/discord-agent-mcp (getting-started + 71-tool reference)
• Discord gateway intents & privileged intent rules: docs.discord.com/developers/events/gateway
• Discord API rate limits: docs.discord.com/developers/topics/rate-limits
• Discord self-bot policy: support.discord.com — Automated User Accounts (Self-Bots)
• Alternative implementation: github.com/iqaicom/mcp-discord (@iqai/mcp-discord on npm, MIT)
• Anthropic’s official Discord plugin: anthropics/claude-plugins-official — external_plugins/discord
• Community / contrarian: r/soc2 — Claude Code Channels (Telegram/Discord) from a SOC 2 perspective
• Web tutorial coverage: Speakeasy — Building an MCP server for Discord
• Canonical MCP.Directory entry: /servers/discord