guildbridge

GuildBridge is an MCP server that provides authenticated, permission-aware access to Discord servers via MCP clients. It authenticates users through Discord OAuth2 and uses a bot token to perform Discord API actions on behalf of the server. The server exposes MCP endpoints under /mcp, enabling tools like list_guilds, list_channels, get_channel_info, read_messages, search_messages, send_message, and reply_to_message. Users must go through the Discord OAuth flow to obtain a valid access token, after which the server computes and enforces RBAC-like permissions based on Discord roles and channel permissions. When testing with the MCP Inspector, you can authenticate via OAuth and then experiment with the available tools to read, search, and post messages in your Discord servers through the MCP interface.

Prerequisites:

• Node.js v18+ installed on your development machine
• A Cloudflare account (optional for deployment) and Wrangler if you plan to deploy on Cloudflare Workers
• A Discord application with a bot user and OAuth2 configured (redirect URIs set for localhost and production)

1. Install dependencies locally

   • Ensure you have Git and Node.js installed
   • In your project directory, run:

   npm install

2. Configure environment and local development files

   • Copy example config files and fill in values:

   cp wrangler.jsonc.example wrangler.jsonc cp .dev.vars.example .dev.vars

   • Edit .dev.vars and provide: DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_BOT_TOKEN, COOKIE_ENCRYPTION_KEY, ALLOWED_DISCORD_USER_IDS

3. Start the development server locally

   • Run:

   npm run dev

   • The server will be available at http://localhost:8788 and MCP endpoint at /mcp.

4. Optional: Deploy to Cloudflare Workers

   • Install and configure Wrangler, then:

   npx wrangler kv namespace create OAUTH_KV (put the resulting ID into wrangler.jsonc replacing PLACEHOLDER_KV_ID)

   npx wrangler secret bulk .dev.vars

   npm run deploy

5. Connect MCP clients

   • Point any MCP-compatible client to: https://<your-worker>.workers.dev/mcp
   • For local testing: http://localhost:8788/mcp

6. Verify with MCP Inspector (optional)

   • Run: npx @modelcontextprotocol/inspector@latest
   • Enter the MCP URL to start OAuth flow and test tools.

Tips and considerations:

• Ensure your Discord OAuth2 redirect URIs are correctly configured for both local development (http://localhost:8788/callback) and your deployed worker URL (https://<your-worker>.workers.dev/callback).
• The server uses two tokens: a bot token (server-side) for Discord API calls and a user OAuth token (inside the MCP access token) for membership verification. The bot token never leaves the server.
• The ALLOWED_DISCORD_USER_IDS setting can be used to restrict access to specific users during development; leave empty to allow all authenticated users.
• When deploying, update wrangler.jsonc with your KV namespace and secrets as instructed by the Cloudflare deployment process.
• If you rotate bot tokens or client secrets, regenerate and update the corresponding environment variables and redeploy.