DiscordMCP

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 Server39 tools"]
        GW["Discord GatewayWebSocket"]
        PE["Policy Engine"]
        AGENT["Agent Service~60 tools"]
        SVC["Discord Service Layer50+ 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["Guild3 tools"]
        CH["Channel8 tools"]
        MSG["Message4 tools"]
        MOD["Moderation2 tools"]
        THR["Thread1 tool"]
        ROLE["Role7 tools"]
        MEM["Member6 tools"]
        WH["Webhook6 tools"]
        INV["Invite4 tools"]
        AUTO["Automation1 tool"]
        AUD["Audit1 tool"]
    end

| Domain | Tools | |--------|-------| | Guild | list, get, modify | | Channel | list, get, create, edit, delete, edit/delete permissions | | Message | listrecent, send, get, edit | | Moderation | delete, bulkdelete | | 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

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](./LICENSE) for details.

Copyright 2026 Luis Gustavo Vaz

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rastrian
• Source: Rastrian/DiscordMCP
• License: Apache-2.0
• Homepage: https://blog.rastrian.dev/post/discordmcp-controlling-servers-through-mcp

Install and usage instructions live in the source repository linked above.