Discord MCP Platform

A multi-server Discord control plane that exposes Discord operations as MCP tools, resources, and prompts for AI clients. Includes a built-in conversational AI agent that responds to Discord @mentions.

What It Does

Users connect their Discord identity via OAuth2, install the platform bot into their servers, and then interact through MCP-compatible AI clients or by @mentioning the bot directly in Discord.

The platform translates natural language requests into safe, authorized Discord operations:

"List my servers and channels"
"Summarize the last 100 messages in #general"
"Create a support channel and set permissions"
"Create an automation that answers FAQs in #support"
"Draft a moderation warning for this message"

What This Is Not

This is not a self-bot. It does not use user tokens, control personal Discord accounts, scrape DMs, or bypass Discord permissions/rate limits. All operations execute through authorized bot accounts using official Discord APIs.

Architecture

graph TD
    subgraph "Clients"
        AI["AI Client / MCP Client"]
        DU["Discord User"]
    end

    subgraph "Platform"
        MCPS["MCP Server<br/>39 tools"]
        GW["Discord Gateway<br/>WebSocket"]
        PE["Policy Engine"]
        AGENT["Agent Service<br/>~60 tools"]
        SVC["Discord Service Layer<br/>50+ REST methods"]
    end

    AI -->|MCP call| MCPS
    DU -->|"@mention"| GW
    MCPS --> PE
    GW --> AGENT
    AGENT --> PE
    PE --> SVC
    SVC -->|API v10| DISC["Discord API"]

graph LR
    subgraph "Authorization Flow"
        direction TB
        A1["1. MCP client auth"] --> A2["2. Workspace membership"]
        A2 --> A3["3. Guild installation check"]
        A3 --> A4["4. Platform role/permission"]
        A4 --> A5["5. Channel policy check"]
        A5 --> A6["6. Discord bot permission"]
        A6 --> A7["7. Rate-limit check"]
        A7 --> A8["8. Execute & audit"]
    end

Features

MCP Server (39 tools)

graph LR
    subgraph "MCP Tools by Domain"
        G["Guild<br/>3 tools"]
        CH["Channel<br/>8 tools"]
        MSG["Message<br/>4 tools"]
        MOD["Moderation<br/>2 tools"]
        THR["Thread<br/>1 tool"]
        ROLE["Role<br/>7 tools"]
        MEM["Member<br/>6 tools"]
        WH["Webhook<br/>6 tools"]
        INV["Invite<br/>4 tools"]
        AUTO["Automation<br/>1 tool"]
        AUD["Audit<br/>1 tool"]
    end

| Domain | Tools | |--------|-------| | Guild | list, get, modify | | Channel | list, get, create, edit, delete, edit/delete permissions | | Message | list_recent, send, get, edit | | Moderation | delete, bulk_delete | | Thread | create | | Role | list, create, modify, delete, reorder, assign, remove | | Member | get, list, kick, ban, timeout, unban | | Webhook | create, list, get, modify, delete, execute | | Invite | create, list, get, delete | | Automation | draft | | Audit | list |

All state-changing tools support dry-run (default on). Risky operations require explicit confirmation. Every write is audited.

Conversational Agent

sequenceDiagram
    participant U as Discord User
    participant GW as Gateway
    participant AG as Agent Service
    participant LLM as LLM API
    participant BOT as Discord Bot

    U->>GW: @mention bot
    GW->>AG: MESSAGE_CREATE event
    AG->>AG: Check guild + channel allowlist
    AG->>AG: Load channel conversation history
    AG->>LLM: Send history + 60 tool definitions
    loop Tool-use loop (max 10 iterations)
        LLM-->>AG: Tool call or text response
        AG->>BOT: Execute tool call
        BOT-->>AG: Tool result
        AG->>LLM: Send tool result
    end
    AG->>BOT: Send final response to channel
    BOT-->>U: Bot reply

~60 agent tools covering the full Discord API surface
Per-channel conversation history
Per-user cooldown
Admin-controlled via /allow-chat and /disallow-chat slash commands

Data Model

erDiagram
    User ||--o{ WorkspaceMembership : "belongs to"
    User ||--o{ OAuthAccount : "has"
    Workspace ||--o{ WorkspaceMembership : "contains"
    Workspace ||--o{ GuildInstallation : "owns"
    Workspace ||--o{ MCPClient : "issues"
    GuildInstallation ||--o{ BotConfig : "has"
    GuildInstallation ||--o{ GuildPolicy : "enforces"
    GuildInstallation ||--o{ ChannelPolicy : "enforces"
    GuildInstallation ||--o{ Automation : "runs"
    GuildInstallation ||--o{ AllowedChatChannel : "allows"
    AuditEvent }o--|| Workspace : "records in"

Infrastructure

Discord Gateway WebSocket with auto-reconnect
Discord REST client with rate limit tracking and automatic retry
Scope-based permission engine with guild/channel allowlists
Audit logging with PII redaction
14 database models (PostgreSQL)
Redis for caching and rate-limit coordination

Quick Start

cp .env.example .env
# Edit .env with your Discord bot token and other settings
docker compose up --build

Health check:

curl http://localhost:8000/health

Development

make install    # install dependencies
make dev        # run dev server with reload
make test       # run tests (no real Discord token needed)
make lint       # ruff check
make format     # ruff format
make typecheck  # mypy
make up         # docker compose up --build
make down       # docker compose down

Environment Variables

Key variables (see .env.example for full list):

| Variable | Description | |----------|-------------| | DISCORD_BOT_TOKEN | Discord bot token | | DISCORD_CLIENT_ID | Discord OAuth client ID | | DISCORD_CLIENT_SECRET | Discord OAuth client secret | | DATABASE_URL | PostgreSQL connection string | | REDIS_URL | Redis connection string | | ALLOWED_GUILD_IDS | Comma-separated guild allowlist (empty = all) | | MCP_TRANSPORT | http or stdio | | ENABLE_GATEWAY | Enable Discord Gateway WebSocket | | AGENT_ENABLED | Enable conversational AI agent | | AGENT_API_KEY | LLM API key for the agent |

MCP Client Configuration

Local STDIO mode:

{
  "mcpServers": {
    "discord": {
      "command": "uv",
      "args": ["run", "python", "-m", "discord_mcp_platform.mcp.server"],
      "env": {
        "DISCORD_BOT_TOKEN": "your-bot-token"
      }
    }
  }
}

HTTP mode: the MCP server is available at http://localhost:8000/mcp when MCP_TRANSPORT=http.

Acknowledgements

Discord API types and endpoint coverage are based on the official Discord OpenAPI specification.

Tech Stack

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

MCP Servers