Discord MCP Server

Control your Discord server using AI — 44 tools, no cloning required. Works with any MCP-compatible app: Claude Desktop, Cursor, Windsurf, Continue.dev, Zed, Claude Code, and more.

What is MCP? Model Context Protocol is an open standard that lets AI apps talk to external tools. This project is one of those tools — it gives any AI assistant the power to manage your Discord server.

Install in one line

npx -y mcp-discord-bridge

That's it — no clone, no npm install. Just add it to your AI app's MCP config (see Quick Start below).

What Can It Do?

Once connected, your AI assistant can:

• Channels — create, delete, rename, move channels and categories
• Messages — read, send, edit, delete, search messages, send DMs, add/remove reactions
• Forum Channels — list forums, create/read/reply/delete forum posts
• Webhooks — create, send via, edit, and delete webhooks
• Members — list members, view profiles, check roles
• Roles — list, create, edit, delete, assign, and remove roles
• Moderation — kick, ban, unban, timeout members, set nicknames
• Threads — create, list, archive, unarchive, join, and delete threads
• Server — list all servers the bot is in, view channel layouts

It also runs as a standalone Discord bot with /ping, /info, and /serverinfo slash commands.

Quick Start (3 minutes)

Step 1: Create a Discord Bot

1. Go to the Discord Developer Portal
2. Click New Application — give it a name
3. Go to Bot tab — click Reset Token — copy and save the token somewhere safe

Step 2: Invite the Bot to Your Server

1. In the Developer Portal, go to OAuth2 > URL Generator
2. Check these scopes: bot, applications.commands
3. Check these permissions: Send Messages, Read Message History, Manage Channels, Manage Roles, Manage Webhooks, Kick Members, Ban Members, Moderate Members, Manage Nicknames
4. Open the generated URL — select your server — authorize

Step 3: Add to Your AI App

Add this to your app's MCP config — no cloning or installing needed:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "mcp-discord-bridge"],
      "env": {
        "DISCORD_TOKEN": "paste_your_bot_token_here"
      }
    }
  }
}

Where is the config file?

Step 4: Done!

Restart your AI app. You should now see Discord tools available. Try asking:

"List all channels in my Discord server"

All Available Tools (44)

Install from Source (for contributors)

If you want to modify the code or run the standalone bot:

git clone https://github.com/iprashantraj/mcp-discord-bridge.git
cd mcp-discord-bridge
npm install
cp .env.example .env   # fill in DISCORD_TOKEN, CLIENT_ID, GUILD_ID

Then use ts-node to run directly:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["ts-node", "/full/path/to/mcp-discord-bridge/mcp-server.ts"],
      "env": {
        "DISCORD_TOKEN": "paste_your_bot_token_here"
      }
    }
  }
}

Running as a Standalone Bot

If you just want the slash commands without MCP:

# Register commands (one time)
npm run deploy-commands

# Start the bot
npm run bot

Docker Deployment

The image defaults to the MCP server (stdio). To run the standalone bot 24/7 instead, uncomment the command: ["node", "dist/index.js"] line in docker-compose.yml, then:

docker-compose up -d       # Start in background
docker-compose logs -f     # View logs

Architecture

An MCP client talks to mcp-server.ts over stdio (JSON-RPC). The server advertises tools (with read-only/destructive annotations), then dispatches each call through mcp-handlers.ts — a 44-tool registry that validates args, checks bot permissions, and enforces read-only mode. Handlers act through the shared client from discord-client.ts, which owns login and connection state. The standalone bot (index.ts) is a separate entrypoint that reuses the same client factory.

Editable source: assets/architecture.excalidraw — open it at excalidraw.com.

Development

npm run typecheck    # Type check
npm run lint         # Lint
npm run test         # Run tests (59 tests)
npm run format       # Format code

CI runs automatically on every push and PR via GitHub Actions.

Project Structure

mcp-discord-bridge/
├── discord-client.ts     # Shared Discord client setup
├── mcp-server.ts         # MCP server (tool schemas + wiring)
├── mcp-handlers.ts       # Tool handler logic (registry pattern)
├── index.ts              # Standalone bot (slash commands)
├── deploy-commands.ts    # One-time command registration
├── tests/                # Vitest test suite
├── .github/workflows/    # CI pipeline
└── Dockerfile            # Multi-stage Docker build

Read-Only Mode

This server can delete channels, ban members, and remove roles. If you only want the AI to read your server, set DISCORD_READONLY in the env block:

"env": {
  "DISCORD_TOKEN": "your_token",
  "DISCORD_READONLY": "true"
}

In read-only mode only the 10 read tools (list_*, get_*, search_messages) are advertised and callable; every write/destructive tool is refused.

All tools also carry MCP annotations (readOnlyHint / destructiveHint), so compatible clients can flag or confirm destructive actions before running them.

Security

• Never commit your .env file — it's already in .gitignore
• Treat your DISCORD_TOKEN like a password — if leaked, regenerate it immediately in the Developer Portal
• The bot can only assign roles below its own role in the hierarchy (Discord enforces this)
• Grant the bot only the permissions you need — if you won't use moderation, don't grant Ban/Kick
• Because the AI can read channel messages and act on the server, treat untrusted message content as a prompt-injection risk; use read-only mode for safer deployments
• See SECURITY.md for the full threat model and reporting policy

License

MIT — use it however you want.