GuildBridge

GuildBridge provides authenticated, permission-aware access to Discord via an MCP server deployed as a Cloudflare Worker. It enables AI agents to read, search, and post messages in Discord servers you authorize, while enforcing access control server-side.

How to use

You deploy GuildBridge on Cloudflare and connect your MCP clients to the provided MCP endpoint. Your MCP client authenticates via Discord OAuth2 and then uses the MCP path to perform tool actions such as listing guilds, listing channels, reading messages, and sending messages. The server enforces permissions so users can only access content they are allowed to see.

How to install

Prerequisites you need before installing GuildBridge:

• Node.js (v18+)

• A Cloudflare account (free tier sufficient)

• A Discord application with a bot user added to your target servers

• OAuth2 configured with client ID and client secret

Then follow these steps to set up and run GuildBridge locally for development or deployment.

# Install dependencies
npm install

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

# Start the development server
npm run dev

Additional notes

Prerequisites required during setup include creating a Discord application, obtaining bot tokens, and configuring OAuth2 redirects for local development and production deployment.

When deploying to Cloudflare, you create a KV namespace and set secrets for the OAuth flow, then deploy the worker. After deployment, the worker URL becomes your MCP endpoint.

You can connect an MCP client to the server using the MCP URL path /mcp on the deployed worker or on your local development server.

Key flow details include the OAuth process, token handling, and how access control is enforced for each tool call.

Prerequisites

• Node.js (v18+)

• A Cloudflare account (free tier is sufficient)

• A Discord application with a bot user added to your servers and OAuth2 configured (client ID + client secret)

Discord App Setup

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

2. Under Bot, click Reset Token to obtain the bot token and save it.

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

4. Under OAuth2 Redirects, add your callback URL for local development and production.

5. Under OAuth2 Scopes, select identify and guilds.

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 servers using the OAuth2 URL Generator with the bot scope and permissions: View Channels, Read Message History, Send Messages.

Local Development

Install dependencies, copy example config files, and start the development server.

# 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

Deploy to Cloudflare

Create the KV namespace and set secrets for local development, then deploy the worker. After deployment, you will receive a worker URL that serves as your MCP endpoint.

# Create the KV namespace
npx wrangler kv namespace create OAUTH_KV

# Set secrets from your environment file
npx wrangler secret bulk .dev.vars

# Deploy to Cloudflare
npm run deploy

Connect an MCP Client

Point your MCP client at the server MCP endpoint. For deployment, use the provided worker URL path /mcp.

Example endpoints to connect to (replace with your actual worker URL):

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

Tools

Available actions include listing guilds, listing channels, retrieving channel information, reading messages, searching messages, sending messages, and replying to messages.

Token Usage

GuildBridge uses two tokens with separate roles: a bot token for all Discord API calls and a user OAuth token used for guild membership verification. The user token is encrypted inside the MCP access token and never stored server-side.

Access Control

Access control verifies guild membership and channel visibility before performing actions. The server computes permissions based on the user's roles and guild context, ensuring that only permitted content is accessible.

Notes on Security and Data

During OAuth, short-lived session state is managed with CSRF and state tokens, and approved clients cookies help streamline return visits without repeated approvals.

Contributing

Contribute by following standard contribution guidelines and review policies for the project. You can review code, tests, and documentation to help improve the MCP server experience.

Available tools

list_guilds

List servers the bot is in

list_channels

List channels in a server, optionally filtered by type

get_channel_info

Get channel details such as topic and type

read_messages

Read messages from a channel with pagination

search_messages

Search messages by content, channel, or author

send_message

Send a message to a channel

reply_to_message

Reply to a specific message