Discord MCP

discord-mcp

An MCP server over the real Discord REST API -- so a Claude agent calls list_channels(guild_id="...") instead of hand-rolling an authenticated httpx request. Built to the github-mcp/bus-mcp standard in this portfolio (own pyproject, fastmcp server, typed errors, real test suite, honest README) -- fifth flagship, first over Discord.

5 read-only tools, always on + 7 write tools, gated OFF by default behind DISCORD_MCP_ENABLE_WRITE=1 -- see "Write tools" below.

Quickstart (60 seconds)

python -m venv .venv

.venv/Scripts/python.exe -m pip install -e ".[test]"

Add to your Claude Desktop/Code MCP config:

{

"mcpServers": { "discord-mcp": { "command": "python", "args": ["C:/path/to/discord-mcp/run_server.py"], "env": { "DISCORD_BOT_TOKEN": "your-bot-token-here" } } } }

Without DISCORD_BOT_TOKEN set, every tool call still returns a clean structured error (Discord's own 401) instead of crashing -- see "Typed errors" below. Write tools also need DISCORD_MCP_ENABLE_WRITE=1 in the same env block, or they refuse locally with policy_refusal -- see "Write tools" below.

What this is / is not

This is a reference portfolio implementation demonstrating an MCP server over a real external SaaS API (Discord) -- it is NOT an official Discord MCP server, and it is not affiliated with Discord Inc. It started from an earlier, separate sibling project's HttpDiscordClient, a stdlib-urllib Discord transport built and verified against a real live guild for that project's own server-provisioning tooling. This repo hand-adapts that client's request-building, header construction (including its deliberately descriptive User-Agent -- see below), and error handling onto httpx (matching this fleet's other MCP servers) as its own standalone client with no dependency on that sibling project. discord-mcp does not import from or depend on that other package at all.

Started as 5 read-only tools with no write capability at all; now ships a 7-tool write group, off by default, mirroring the *_MCP_ENABLE_WRITE-style gate already shipped in github-mcp/bus-mcp/desktop-mcp in this same portfolio -- see "Write tools" below.

Tools

Read (always on, no gate)

Write (gated behind DISCORD_MCP_ENABLE_WRITE=1, default OFF)

Write tools

Seven write tools were added on top of the original 5 read-only tools, mirroring the exact write-gate pattern already shipped in this portfolio (github-mcp's GITHUB_MCP_ENABLE_WRITE, desktop-mcp's DESKTOP_MCP_ENABLE_*, and most closely bus-mcp's BUS_MCP_ENABLE_WRITE + gated_write decorator, copied as the reference template). create_message was added a night later than the other 6, once it became clear that none of create_channel/edit_channel/create_role/edit_role/edit_guild/delete_channel can actually post content to a channel -- it reuses the exact same gate and the post() helper create_channel/create_role already added to client.py, no new HTTP plumbing.

• Off by default. Set DISCORD_MCP_ENABLE_WRITE=1 (or true/yes/on) in the server's environment to enable the write group. Unset (or any other value) means every write tool call refuses locally, with zero Discord API calls attempted, returning a structured policy_refusal error:

  {"ok": false, "error": {"type": "policy_refusal", "message": "Tool group 'write' is disabled. Set DISCORD_MCP_ENABLE_WRITE=1 in the server's environment to enable it.", "group": "write", "tool": "create_channel", "required_env": "DISCORD_MCP_ENABLE_WRITE"}}

• Enforced at the route layer, not just the MCP-tool layer. The @config.gated_write decorator wraps each write function directly in discord_mcp/routes.py (not merely the @mcp.tool wrapper in server.py), so the gate is unit-testable without spinning up fastmcp or a real transport, and can't be bypassed by any alternate calling path into routes.py.
• Read fresh from the environment on every call, never cached at import time -- an operator can arm/disarm the write group without restarting the server process, and tests can monkeypatch it per-test.
• `delete_channel` gets no separate or lower bar. Despite being genuinely destructive/irreversible against a real guild, it is gated behind the exact same DISCORD_MCP_ENABLE_WRITE env var as the other write tools -- confirmed by dedicated tests in test_routes.py (setting plausible-but-wrong var names like DISCORD_MCP_ENABLE_DELETE does not arm it).
• Same auth path as the read tools. Write calls reuse the exact same _headers()/pooled httpx.AsyncClient construction in client.py as every read tool -- there is only one auth code path in this repo.
• `create_message` validates content locally, not just via Discord's own 400. content must be a non-empty string of at most 2000 characters (Discord's real message-length limit) -- checked by client.validate_message_content before any request is built, same "never even attempt the call" discipline as the snowflake-id checks. A violation returns validation_error, not a raw Discord 400.

icon_base64/banner_base64 on edit_guild -- a flagged assumption

Discord's docs describe PATCH /guilds/{id}'s icon/banner fields as an "image data" string -- a full data URI (data:image/png;base64, ), not a bare base64 payload. edit_guild accepts either:

• a full data:...;base64,... URI, passed through unchanged, or
• raw base64 bytes, which are assumed to be PNG and wrapped as data:image/png;base64, .

This PNG assumption is not verified against a real Discord response -- this repo has not confirmed whether Discord accepts, rejects, or silently mis-renders a non-PNG image (JPEG, animated GIF for boosted-server icons, etc.) sent under an image/png label. If you have a non-PNG image, pass a full data:image/...;base64,... URI yourself rather than relying on the default. Flagged here rather than guessed silently.

Typed errors, never a raw crash

Every tool returns {"ok": true, ...} on success or {"ok": false, "error": {...}} on failure -- never an unhandled exception or stack trace.

• `network_error` -- connection refused, timeout, DNS failure, or a malformed request URL. Discord's API wasn't reachable at all.
• `auth_error` (401) -- missing or invalid bot token.
• `permission_error` (403, with Discord's own JSON error body, e.g. {"message": "Missing Access", "code": 50001}) -- the bot lacks the permission/scope for this call, or isn't in the guild.
• `cloudflare_blocked` (403, with no JSON error body) -- Discord's API docs ask for a descriptive User-Agent; without one, a client's default UA is a well-known bot fingerprint that Discord's Cloudflare edge can reject with a bare 403 *before* the request ever reaches route-level permission checks. This is otherwise indistinguishable from a real permission_error 403 -- Discord's real permission-denied responses always carry a JSON body, so absence of a JSON body on a 403 is the signal this type is built on. This is a best-effort heuristic, not a certainty: a proxy, load balancer, or future Discord change that strips the body on a *different* kind of 403 would also land here. discord-mcp sends the same descriptive User-Agent this heuristic exists to explain (see client.py's _headers()), so in practice this type should rarely fire from this server's own calls -- see "Honest limitations" below.
• `not_found` (404) -- bad/unknown guild, channel, role, or member id.
• `rate_limited` (429) -- Discord's rate limit. Carries retry_after_s, parsed straight from Discord's own JSON body (retry_after, in seconds). This server does not auto-retry -- it surfaces the limit as a structured error immediately and leaves any backoff/retry decision to the caller.
• `decode_error` -- a 2xx response whose body isn't valid JSON (should not happen against the real API; guards against a malformed proxy/mock).
• `discord_api_error` -- any other 4xx/5xx not covered above.
• `policy_refusal` (write tools only) -- the write group is disabled; see "Write tools" above. No Discord API call is attempted.
• `invalid_id` -- a guild/channel/role/member id failed snowflake-shape validation before any request was built (defense against path injection).
• `validation_error` (create_message only) -- content was empty or exceeded Discord's real 2000-character message limit, caught before any request was built.

Internally, discord_mcp/client.py raises typed DiscordUnreachable / DiscordApiError (with a DiscordDecodeError subclass for the 2xx-non-JSON case) exceptions; discord_mcp/routes.py catches both and normalizes to the dict shape above before a tool ever returns. Tests exercise both layers for every error type, across every HTTP verb (GET/POST/PATCH/DELETE).

Honest limitations

• The cloudflare_blocked vs. permission_error split is a heuristic (JSON-body-present-or-not), not something Discord documents or guarantees. It is accurate for the specific failure mode it was written to explain (an edge reject due to a missing/generic User-Agent) but a 403 with a stripped body from an unrelated cause (e.g. a misbehaving proxy in between) would also be classified as cloudflare_blocked.
• get_channel_permission_overwrites and get_member_roles were not exercised against every possible real-world edge case (e.g. a member with zero roles, a channel with zero overwrites) via the live smoke test -- only via respx-mocked unit tests. The live smoke test only calls list_channels/list_roles; it does not exercise any write tool.
• No pagination is implemented anywhere. list_channels/list_roles are single-request, unpaginated Discord endpoints (Discord doesn't paginate either of these), so this is a non-issue for the tools in scope -- but a guild large enough to need member-list pagination is out of scope entirely (there is no list_members tool here).
• The icon_base64/`banne