jaimenbell/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)
Add to your Claude Desktop/Code MCP config:
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) | Role ids currently assigned to one guild member |
Write (gated behind DISCORD_MCP_ENABLE_WRITE=1, default OFF)
| Tool | Discord endpoint | Purpose |
|---|---|---|
| create_channel | POST /guilds/{guild_id}/channels | Create a text/voice/category channel |
| edit_channel | PATCH /channels/{channel_id} | Rename/re-topic/re-parent/reorder an existing channel |
| create_role | POST /guilds/{guild_id}/roles | Create a role |
| edit_role | PATCH /guilds/{guild_id}/roles/{role_id} | Edit an existing role |
| edit_guild | PATCH /guilds/{guild_id} | Update guild-level identity (name/icon/banner/description) |
| delete_channel | DELETE /channels/{channel_id} | **Destructive.** Delete a channel |
| create_message | POST /channels/{channel_id}/messages | Post a message to a text channel (content: non-empty, ),
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