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.

Parameter	Type	Required	Description
guild_id	string	Yes	Discord server/guild ID

discord_send_message

Sends a plain text message to a channel.

Parameter	Type	Required	Description
channel	string	Yes	Channel ID or name (e.g. "general")
content	string	Yes	Message text (max 2000 chars)
guild_id	string	No	Server ID. Required if channel is a name and no default is set.

discord_read_messages

Reads recent messages from a channel.

Parameter	Type	Required	Description
channel	string	Yes	Channel ID or name
guild_id	string	No	Server ID. Required if channel is a name and no default is set.
limit	integer	No	Number of messages (default: 10, max: 50)

discord_send_embed

Sends a rich embed message to a channel.

Parameter	Type	Required	Description
channel	string	Yes	Channel ID or name
title	string	Yes	Embed title (max 256 chars)
description	string	No	Embed body text (max 4096 chars)
color	integer	No	Color as decimal (e.g. 3447003 for blue)
fields	list	No	List of {name, value, inline} objects (max 25 fields)
content	string	No	Plain text alongside the embed
guild_id	string	No	Server ID. Required if channel is a name and no default is set.

Environment Variables

Variable	Required	Description
DISCORD_BOT_TOKEN	Yes	Bot token from Discord Developer Portal
DISCORD_DEFAULT_GUILD_ID	No	Default server ID for all tool calls

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