GuildBridge

About

There is no official Discord MCP server, yet much of the coordination with contributors in the MCP community happens on Discord. GuildBridge fills that gap for me — it gives MCP clients authenticated, permission-aware access to Discord servers so that AI agents can read, search, and post messages where the conversation is already happening. It very much came to life on the heels of a problem that I had that I solved by building my own MCP server.

Prerequisites

• Node.js (v18+)

• A Cloudflare account (using the free tier is sufficient)

• A Discord application with:

  • A bot user added to the servers you want to access

  • OAuth2 configured (client ID + secret)

Discord App Setup

1. Go to the Discord Developer Portal and create (or select) an application.

2. Under Bot, click "Reset Token" to get your bot token. Save it.

3. Under OAuth2, note the Client ID and Client Secret.

4. Under OAuth2 > Redirects, add your callback URL:

   • Local dev: http://localhost:8788/callback

   • Production: https://<your-worker>.workers.dev/callback (you will get this URI later when you deploy your MCP server to Cloudflare)

5. Under OAuth2 > Scopes, ensure identify and guilds are selected.

6. Under Bot > Privileged Gateway Intents, enable Message Content Intent if you want full message content in search results.

7. Invite the bot to your server(s) using the OAuth2 URL Generator with the bot scope and these permissions: View Channels, Read Message History, Send Messages.

Local Development

# Install dependencies
npm install

# Copy the example files and fill in your values
cp wrangler.jsonc.example wrangler.jsonc
cp .dev.vars.example .dev.vars

# Start the dev server
npm run dev

The server runs at http://localhost:8788. The MCP endpoint is at /mcp.

.dev.vars

Deploy to Cloudflare

# Create the KV namespace (https://developers.cloudflare.com/kv/)
npx wrangler kv namespace create OAUTH_KV

Copy the output id into wrangler.jsonc replacing PLACEHOLDER_KV_ID.

# Set secrets (https://developers.cloudflare.com/workers/configuration/secrets/)
npx wrangler secret bulk .dev.vars

# Deploy
npm run deploy

After deploying, Wrangler will print your worker URL (e.g. https://guildbridge.<your-subdomain>.workers.dev). Add https://<your-worker-url>/callback as a redirect URI in the Discord Developer Portal.

Connect an MCP Client

Point any MCP-compatible client at the server URL:

https://<your-worker>.workers.dev/mcp

Or locally:

http://localhost:8788/mcp

To test with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest

Enter the URL above, complete the Discord OAuth flow, and the tools will become available.

Tools

Access Control

Every tool call goes through a layered access check before touching the Discord API. Guild membership is verified via the user's OAuth token, and channel visibility is enforced by computing Discord's permission algorithm from the bot's perspective.

flowchart TD
    A[Tool call] --> B{Channel or guild scoped?}

    B -->|Guild scoped| C[assertGuildAccess]
    B -->|Channel scoped| D[assertChannelAccess]

    C --> E[Fetch user guilds via OAuth token]
    E --> F{User is member?}
    F -->|No| G[Access denied]

    D --> H[Fetch channel info via bot token]
    H --> I{Channel in a guild?}
    I -->|No| G
    I -->|Yes| C

    F -->|Yes| J[getGuildPermContext]
    J --> K[Fetch guild roles + member roles + guild info]
    K --> L{User is guild owner?}
    L -->|Yes| M[Access granted]
    L -->|No| N[computePermissions]

    N --> O[Base: @everyone role perms]
    O --> P[OR in member role perms]
    P --> Q{ADMINISTRATOR set?}
    Q -->|Yes| M
    Q -->|No| R[Apply @everyone channel overwrite]
    R --> S[Apply matching role channel overwrites]
    S --> T[Apply member-specific channel overwrite]
    T --> U{VIEW_CHANNEL set?}
    U -->|Yes| M
    U -->|No| G

For list_channels and search_messages, the same permission computation is applied as a post-filter — channels the user can't see are stripped from results.

Token Usage

GuildBridge uses two distinct Discord tokens with intentionally separate roles:

The bot token never leaves the server. The user's Discord OAuth token is obtained during the OAuth2 login flow, embedded into an encrypted MCP access token, and returned to the MCP client. GuildBridge does not store the user's token server-side — the MCP client holds the encrypted token and sends it with each request, where it is decrypted to extract the OAuth token for guild membership checks.

sequenceDiagram
    participant Client as MCP Client
    participant Server as GuildBridge
    participant Discord as Discord API

    note over Client,Discord: OAuth Flow (one-time setup)
    Client->>Server: Connect to /mcp
    Server-->>Client: 401 — authenticate via OAuth
    Client->>Server: /authorize
    Server->>Discord: Redirect to Discord OAuth
    Discord-->>Server: /callback with auth code
    Server->>Discord: Exchange code for user OAuth token
    Discord-->>Server: User OAuth token
    Server-->>Client: Encrypted MCP token (contains user OAuth token)

    note over Client,Discord: Tool Calls (ongoing)
    Client->>Server: Tool call + MCP token (Bearer)
    Server->>Server: Decrypt MCP token → extract user OAuth token
    Server->>Discord: Verify guild membership (Bearer user OAuth token)
    Discord-->>Server: User's guild list
    Server->>Discord: Execute tool action (Bot token from env)
    Discord-->>Server: API response
    Server-->>Client: Tool result

During the OAuth flow, short-lived session state is managed via:

• CSRF token — HTTP-only cookie, validates the approval form submission (600s TTL)

• State token — stored in Cloudflare KV, binds the OAuth request across redirects (600s TTL)

• Approved clients cookie — HMAC-signed, lets returning users skip the approval dialog (30 days)

Contributing

See CONTRIBUTING.md for setup instructions, code style guidelines, and how to submit changes. Please also review the AI Usage Policy before contributing.