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

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):

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

Python 3.12+ | FastAPI | MCP Python SDK | pydantic v2 | httpx | SQLAlchemy 2.x | PostgreSQL | Redis | Docker | pytest

License

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

Copyright 2026 Luis Gustavo Vaz [email protected]