Discord MCP Server

A Python MCP (Model Context Protocol) server that lets you interact with Discord directly from Claude Code sessions. Send messages, read channels, post rich embeds, and list server channels — all through natural conversation with Claude.

Prerequisites

• Docker and Docker Compose installed
• Claude Code CLI installed
• A Discord bot token (setup guide below)

Discord Bot Setup

1. Go to the Discord Developer Portal
2. Click New Application, give it a name, and create it
3. Go to Bot in the left sidebar
4. Click Reset Token and copy the token — this is your DISCORD_BOT_TOKEN
5. Under Privileged Gateway Intents, enable Message Content Intent
6. Go to OAuth2 > URL Generator in the left sidebar
7. Select scopes: bot
8. Select bot permissions: Send Messages, Read Message History, View Channels
9. Copy the generated URL and open it in your browser to invite the bot to your server

Installation

1. Clone the repository

git clone <your-repo-url>
cd discord-mcp-server

2. Set up environment variables

cp .env.example .env
# Edit .env and add your DISCORD_BOT_TOKEN and optionally DISCORD_DEFAULT_GUILD_ID

3. Build the Docker image

docker compose build

4. Register with Claude Code

Add the following to your Claude Code MCP settings. You can configure this in ~/.claude/settings.json (global) or .mcp.json (project-level):

{
  "mcpServers": {
    "discord-mcp": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/discord-mcp-server/docker-compose.yml",
        "run", "--rm", "-i", "discord-mcp"
      ],
      "env": {
        "DISCORD_BOT_TOKEN": "your-bot-token-here",
        "DISCORD_DEFAULT_GUILD_ID": "your-guild-id-here"
      }
    }
  }
}

Note: Replace /absolute/path/to/discord-mcp-server with the actual absolute path to this project on your machine. Replace the token and guild ID with your actual values.

Usage Examples

Once configured, you can use these tools in any Claude Code session:

List channels in a server:

"Show me all the channels in my Discord server"

Send a message:

"Send 'Deployment complete!' to the #general channel"

Read recent messages:

"What are the last 5 messages in #random?"

Send a rich embed:

"Send an embed to #updates with title 'Release v2.0' and a green color, with fields for 'Changes' and 'Breaking Changes'"

Tool Reference

discord_list_channels

Lists all text channels in a Discord server.

discord_send_message

Sends a plain text message to a channel.

discord_read_messages

Reads recent messages from a channel.

discord_send_embed

Sends a rich embed message to a channel.

Environment Variables

Architecture

Claude Code  ←stdio→  MCP Server (Python)  ←HTTPS→  Discord API v10

• src/discord_mcp/types.py — Pydantic models with Discord API limit validation (Channel, Message, SendResult, Embed)
• src/discord_mcp/discord_client.py — Async Discord REST API wrapper using httpx
• src/discord_mcp/server.py — MCP tool definitions and handler functions

Key design decisions:

• All Discord API interaction goes through DiscordClient — never call httpx directly from server.py
• Tool handlers are separated from @mcp.tool() decorators for testability
• Channel names are resolved case-insensitively via the Discord API
• Guild ID follows a fallback chain: explicit parameter → DISCORD_DEFAULT_GUILD_ID env var → None

Security

• Input validation — Guild IDs and channel IDs are validated as numeric Discord snowflakes before use in API URLs
• Content length enforcement — Message content (2000 chars) and all embed fields (title 256, description 4096, field name 256, field value 1024, max 25 fields, 6000 total) are validated before sending to the Discord API
• Embed sanitization — Embed fields are validated through Pydantic models (EmbedField), preventing injection of arbitrary embed properties
• Error message hygiene — Failed channel lookups do not enumerate available channels, preventing server structure disclosure
• Rate limit handling — The client retries once with backoff on 429 responses (capped at 5s)
• Docker hardening — Container runs as a non-root appuser
• Dependency pinning — All dependencies (production and dev) use compatible-release (~=) constraints
• Reproducible builds — requirements-lock.txt pins all transitive dependency versions; Docker builds install from the lock file

Development

Running locally (without Docker)

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

export DISCORD_BOT_TOKEN=your-token
export DISCORD_DEFAULT_GUILD_ID=your-guild-id

discord-mcp

Running tests

pip install -e ".[dev]"
pytest tests/ -v

Tests use respx to mock httpx requests — no real Discord API calls are made.

License

MIT