Discord MCP

Remote MCP server (Streamable HTTP) that exposes Discord as tools, designed to be connected from Claude → Settings → Connectors → Add custom connector (https://claude.ai/ask-your-org/setup, Custom option).

What it exposes

Tools over the Discord API, using discord.py:

• list_guilds — servers the bot has access to.

• list_channels(guild_id) — channels of a server.

• list_members(guild_id, limit) — members of a server.

• list_roles(guild_id) — roles of a server.

• send_message(channel_id, content) — send a message.

• read_messages(channel_id, limit, before_message_id) — read history.

• create_thread(channel_id, name, message_id?, auto_archive_minutes) — create a thread.

• add_reaction(channel_id, message_id, emoji) / remove_reaction(...) — reactions.

• add_role_to_member(guild_id, user_id, role_id) / remove_role_from_member(...) — roles.

All ids (server, channel, message, user, role) are Discord snowflakes, as strings.

Related MCP server: Discord MCP Server

1. Create the Discord bot

1. Go to the Discord Developer Portal and create a New Application.

2. In Bot, create the bot and copy the Token (Reset Token button). That's the value of DISCORD_BOT_TOKEN.

3. In the same Bot → Privileged Gateway Intents section, enable:

   • Server Members Intent (required for list_members and role management).

   • Message Content Intent (required to read message content in read_messages).

4. In OAuth2 → URL Generator:

   • Scopes: bot.

   • Bot Permissions (adjust according to what you'll use): View Channels, Send Messages, Read Message History, Create Public Threads, Add Reactions, Manage Roles.

   • Open the generated URL and invite the bot to the server where you'll use it.

5. If you're going to use add_role_to_member / remove_role_from_member, make sure the bot's role is above (higher hierarchy) the roles you want to assign.

2. Configure environment variables

Copy .env.example to .env and fill it in:

cp .env.example .env

• DISCORD_BOT_TOKEN: the token from the previous step.

• MCP_AUTH_TOKEN: your own secret to protect the server (generate it with python -c "import secrets; print(secrets.token_urlsafe(32))"). Claude.ai will send it as the Authorization: Bearer <token> header on each request (see step 4).

• The rest of the variables have reasonable defaults — see comments in .env.example.

3. Run the server

Local (without Docker)

python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m discord_mcp   # o: discord-mcp

By default it listens on http://0.0.0.0:8000/mcp.

With Docker

docker compose up --build

or manually:

docker build -t discord-mcp .
docker run --env-file .env -p 8000:8000 discord-mcp

Deploy (Render / Railway / Fly.io / any VPS)

The image is a generic stateless HTTP container (the bot's state lives in memory and in Discord), so it runs on any provider that supports Docker:

• Configure the environment variables from step 2 in the provider's panel.

• Expose port 8000 (or whatever you set in PORT) over HTTPS — Claude.ai requires the MCP server to be reachable via https://.

• Once deployed, the connector URL will be https://<your-domain>/mcp.

To strengthen protection against DNS rebinding in production, set ALLOWED_HOSTS (the server's public hostname) and ALLOWED_ORIGINS (for example https://claude.ai).

4. Connect it in claude.ai as a custom connector

1. Go to https://claude.ai/ask-your-org/setup (or Settings → Connectors) and choose Add custom connector / Custom.

2. Name: Discord (or whatever you prefer).

3. URL: https://<your-domain>/mcp.

4. In Request headers / Advanced settings, add:

   • Header: Authorization

   • Value: Bearer <the same value you set in MCP_AUTH_TOKEN>

5. Save and test by asking Claude something like "List the available Discord servers" — it should call list_guilds.

If you prefer not to use authentication (only for quick tests, never in production), leave MCP_AUTH_TOKEN empty and omit the header.

Development

pip install -e ".[dev]"
pytest

The tests cover configuration, the authentication middleware, and the DiscordService logic that doesn't require a real Discord connection (there are no integration tests against the real Discord API).

Architecture notes

• The discord.py bot runs as a background task within the same event loop as the ASGI server (Starlette/uvicorn); it starts and stops along with the app's lifespan (src/discord_mcp/server.py).

• The MCP server uses Streamable HTTP transport (mcp.server.MCPServer from the official mcp SDK), the remote transport supported by Claude's custom connectors.

• Authentication is a static bearer token validated by a custom ASGI middleware (auth_middleware.py), designed for the "Request headers" mechanism of custom connectors — it doesn't implement the full OAuth flow.