An MCP server over the real Discord REST API
-- so a Claude agent calls list_channels(guild_id="...") instead of
hand-rolling an authenticated request. Built to the
/
standard in this portfolio (own pyproject, fastmcp server, typed errors, real
test suite, honest README) -- fifth flagship, first over Discord.
MCP server for the Discord REST API: 5 read tools always on, 7 write tools env-gated, default off.
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)
Tool
Discord endpoint
Purpose
list_channels
GET /guilds/{guild_id}/channels
All channels (every type) in a guild
list_roles
GET /guilds/{guild_id}/roles
All roles in a guild
list_categories
GET /guilds/{guild_id}/channels (filtered)
Category channels only (Discord type 4) -- Discord has no dedicated categories-only endpoint, so this filters the same channels payload client-side
get_channel_permission_overwrites
GET /channels/{channel_id} (permission_overwrites field)
Role/member allow+deny bitfields set on one channel
get_member_roles
GET /guilds/{guild_id}/members/{member_id} (roles field)
Post a message to a text channel (content: non-empty, <= 2000 chars)
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,<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.
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/banner_base64 "assumed PNG" default on edit_guild has
not been verified against a real Discord response -- see "Write tools"
above.
No write tool has been exercised against the real Discord API at all (by
design -- this task's constraints require zero real network calls; the
live smoke test remains read-only-only). This includes create_message
-- it has never posted a real message to a real live guild as part of
this repo's own build/test process; that remains a deliberate, separate
operator action.
Env vars
Var
Default
Purpose
DISCORD_BOT_TOKEN
unset
Bot token, sent as Authorization: Bot <token>. Read-only tools still work without one in the unit test suite (fully mocked); against the real API, a missing token surfaces as a normal auth_error (401) from Discord itself.
DISCORD_MCP_ENABLE_WRITE
unset (OFF)
Set to 1/true/yes/on to enable the 7 write tools. See "Write tools" above.
DISCORD_MCP_TIMEOUT_S
10.0
Per-request timeout (seconds)
DISCORD_MCP_LIVE
unset
Set to 1 to run the real-network smoke test (see Testing)
DISCORD_MCP_SMOKE_GUILD_ID
unset
Guild id the live smoke test targets. Test skips cleanly if unset.
DISCORD_MCP_SMOKE_ENV_PATH
unset
Path to an external .env file to source DISCORD_BOT_TOKEN from for the live smoke test, if not already in the environment.
DISCORD_API_BASE (https://discord.com/api/v10) is a fixed constant, not
env-overridable -- unlike bus-mcp's self-hosted BUS_MCP_BASE_URL, Discord's
REST API has exactly one real base URL.
163 tests: 162 unit tests (respx-mocked, zero real network) + 1 live smoke
(gated, see below). All 12 tools' happy paths are covered, every error type
above is exercised at both the client layer (test_client.py) and the
routes-normalization layer (test_routes.py), and test_server.py actually
asyncio.run()s each @mcp.tool async wrapper function against a
monkeypatched routes module -- not just introspects list_tools() -- so an
arg-name mismatch or dropped kwarg between server.py and routes.py would
be caught.
Write-tool coverage specifically (test_config.py + test_routes.py):
gate-off refusal for each of the 7 write tools with len(respx.calls) == 0
asserted (proving no Discord call is even attempted), gate-on success paths
with mocked Discord responses (including request-body assertions), gate-on
Discord-API-error passthrough (permission/not-found/rate-limit/network/5xx),
and delete_channel specifically double-checked -- both that it refuses
identically to the other write tools, and that no plausible-but-wrong env
var name (DISCORD_MCP_ENABLE_DELETE, etc.) accidentally arms it.
create_message additionally gets dedicated content-length boundary tests
(test_client.py/test_routes.py): exactly 2000 characters is accepted (1
respx call), 2001 characters and an empty string are both rejected locally
as validation_error with zero respx calls.
Live smoke test
tests/test_live_smoke.py::test_live_list_channels_and_roles_against_a_real_guild
is gated behind DISCORD_MCP_LIVE=1 and DISCORD_MCP_SMOKE_GUILD_ID (unset
by default -- both must be set to run) and calls the real Discord API's
list_channels/list_roles against that guild. It sources
DISCORD_BOT_TOKEN from this process's own environment if already set,
otherwise, if DISCORD_MCP_SMOKE_ENV_PATH points at an external .env
file, loads it from there (once, without ever printing or logging the
value) -- this repo has no .env of its own and never will; the real token
lives in a separate operator-controlled location. It remains
read-only-only -- no write tool has a live smoke test.
Register in ~/.claude.json under mcpServers.discord-mcp as a stdio
server invoking run_server.py by absolute path (no cwd needed -- the
entrypoint adds its own directory to sys.path). env: {} in the real
registration -- the real bot token is never baked into ~/.claude.json;
set DISCORD_BOT_TOKEN in whatever process actually launches the server if
you want authenticated calls, and DISCORD_MCP_ENABLE_WRITE=1 if you want
the write group armed. Arming the write gate in the real registration is a
deliberate, separate operator action -- not part of this repo's default
config.
Handshake check
.venv/Scripts/python.exe scripts/list_tools.py
Prints the twelve registered tool names with no transport started -- pure
introspection, useful for verifying the server wires up cleanly after any
change.
Out of scope
Pagination / list_members (see "Honest limitations" above).
Retrying rate-limited (429) requests -- surfaced as a structured error,
left to the caller.
Distinguishing every possible cause of a body-less 403 with certainty
(see the cloudflare_blocked heuristic's honest limitation above).
Any write operation beyond the 7 tools above (e.g. member role
assignment/kick/ban, message edit/delete, embeds/attachments/reactions,
webhook management) -- create_message covers plain-text content only,
no embeds/files/reactions. A broader, differently shaped write-capable
project exists elsewhere in this author's portfolio with an
apply_server_structure-style tool, out of scope here.
Commercial support
Maintained by Jaimen Bell. For production MCP
integrations, custom servers, or agent-reliability work, see
jaimenbell.dev.
Building your own MCP server? The MCP Starter Kit
has templates, a build playbook, and packaging war-stories from shipping this one.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Discord?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Discord necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Discord?
Discord se ejecuta localmente por stdio.
¿Cuándo se comprobó Discord por última vez?
Última comprobación: 2026-11-09. MCP server for the Discord REST API: 5 read tools always on, 7 write tools env-gated, default off.