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:
  config.json

  Copy

  {"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,<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,<value>.

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.