# iprashantraj/mcp-discord-bridge [Health: Active] **Category:** ๐Ÿ’ฌ Communication **Repository:** https://github.com/iprashantraj/mcp-discord-bridge **GitHub Stars:** 3 **npm Downloads (last month):** 79 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/iprashantraj-mcp-discord-bridge ## Description Discord MCP server with 46 tools for channels, messages, forums, webhooks, members, roles, threads, and moderation. Zero-install via npx -y mcp-discord-bridge. Also runs as a standalone bot with slash commands. ## Tools Capabilities this server exposes over MCP: - **list_guilds** โ€” List all Discord servers the bot is in - **list_channels** โ€” List all channels and categories in a Discord server - **create_category** โ€” Create a new category in a Discord server - **create_channel** โ€” Create a text or voice channel, optionally inside a category - **delete_channel** โ€” Delete a channel or category by ID - **move_channel** โ€” Move a channel into a different category - **rename_channel** โ€” Rename a channel or category - **get_channel_messages** โ€” Fetch recent messages from a text channel - **send_message** โ€” Send a message to a Discord text channel - **delete_message** โ€” Delete a message by channel and message ID - **edit_message** โ€” Edit a bot message by channel and message ID - **search_messages** โ€” Search the 100 most recent messages in a channel by keyword (Discord exposes no full-history search to bots) - **send_dm** โ€” Send a direct message to a user - **add_reaction** โ€” Add an emoji reaction to a message - **remove_reaction** โ€” Remove the bot's emoji reaction from a message - **add_multiple_reactions** โ€” Add multiple emoji reactions to a message at once - **list_forum_channels** โ€” List all forum channels in a server - **create_forum_post** โ€” Create a new forum post with title and content - **get_forum_post** โ€” Fetch a forum post and its messages - **reply_to_forum_post** โ€” Reply to an existing forum post - **delete_forum_post** โ€” Delete a forum post - **create_webhook** โ€” Create a webhook for a channel - **send_webhook_message** โ€” Send a message via a webhook - **edit_webhook** โ€” Edit an existing webhook - **delete_webhook** โ€” Delete a webhook - **list_members** โ€” List members in a Discord server (up to 1000) - **get_member** โ€” Get detailed information about a specific guild member - **list_roles** โ€” List all roles in a Discord server - **assign_role** โ€” Assign a role to a guild member - **remove_role** โ€” Remove a role from a guild member - **kick_member** โ€” Kick a member from the server - **ban_member** โ€” Ban a user from the server - **unban_member** โ€” Unban a user from the server - **timeout_member** โ€” Timeout (mute) a member for a specified duration - **set_nickname** โ€” Set or reset a member's nickname - **create_role** โ€” Create a new role in the server - **edit_role** โ€” Edit an existing role's name or color - **delete_role** โ€” Delete a role from the server - **create_thread** โ€” Create a new thread in a text channel - **list_threads** โ€” List active and archived threads in a channel - **archive_thread** โ€” Archive a thread, optionally locking it - **unarchive_thread** โ€” Unarchive a thread - **join_thread** โ€” Make the bot join a thread - **delete_thread** โ€” Delete a thread ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "mcp-discord-bridge": { "command": "npx", "args": ["-y","mcp-discord-bridge"], "env": { "DISCORD_TOKEN": "" } } } ``` **Requires environment variables:** `DISCORD_TOKEN` โ€” the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README # Discord MCP Server [![npm version](https://img.shields.io/npm/v/mcp-discord-bridge.svg)](https://www.npmjs.com/package/mcp-discord-bridge) [![npm downloads](https://img.shields.io/npm/dm/mcp-discord-bridge.svg)](https://www.npmjs.com/package/mcp-discord-bridge) [![CI](https://github.com/iprashantraj/mcp-discord-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/iprashantraj/mcp-discord-bridge/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) 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.

Demo showing Discord MCP tools in action

## Install in one line ```bash 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](#quick-start-3-minutes) 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](https://discord.com/developers/applications) 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**: ```json { "mcpServers": { "discord": { "command": "npx", "args": ["-y", "mcp-discord-bridge"], "env": { "DISCORD_TOKEN": "paste_your_bot_token_here" } } } } ``` **Where is the config file?** | App | Config Location | |-----|----------------| | **Claude Desktop** | Windows: `%APPDATA%\Claude\claude_desktop_config.json` ยท macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` | | **Claude Code** | `~/.claude.json` (or run `/mcp` in Claude Code) | | **Cursor** | Settings > search "MCP" > Edit MCP Settings | | **Windsurf** | `~/.codeium/windsurf/mcp_settings.json` | | **Continue.dev** | `~/.continue/config.json` | | **Zed** | `~/.config/zed/settings.json` | ### 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) | Tool | What It Does | |------|-------------| | **Server** | | | `list_guilds` | List all servers the bot is in | | `list_channels` | List all channels and categories | | **Channels** | | | `create_category` | Create a new category | | `create_channel` | Create a text or voice channel | | `delete_channel` | Delete a channel or category | | `move_channel` | Move a channel to a different category | | `rename_channel` | Rename a channel or category | | **Messages** | | | `get_channel_messages` | Fetch recent messages (up to 100) | | `send_message` | Send a message to a channel | | `delete_message` | Delete a message | | `edit_message` | Edit a bot message | | `search_messages` | Search messages by keyword | | `send_dm` | Send a direct message to a user | | `add_reaction` | Add an emoji reaction to a message | | `remove_reaction` | Remove the bot's reaction from a message | | `add_multiple_reactions` | Add multiple reactions at once | | **Forum Channels** | | | `list_forum_channels` | List all forum channels in a server | | `create_forum_post` | Create a new forum post | | `get_forum_post` | Fetch a forum post and its messages | | `reply_to_forum_post` | Reply to a forum post | | `delete_forum_post` | Delete a forum post | | **Webhooks** | | | `create_webhook` | Create a webhook for a channel | | `send_webhook_message` | Send a message via webhook | | `edit_webhook` | Edit a webhook | | `delete_webhook` | Delete a webhook | | **Members** | | | `list_members` | List server members with roles | | `get_member` | Get detailed info about a member | | **Roles** | | | `list_roles` | List all roles in a server | | `assign_role` | Give a role to a member | | `remove_role` | Take a role from a member | | `create_role` | Create a new role with name, color, mentionable | | `edit_role` | Edit a role's name or color | | `delete_role` | Delete a role from the server | | **Moderation** | | | `kick_member` | Kick a member from the server | | `ban_member` | Ban a user (with optional message cleanup) | | `unban_member` | Unban a previously banned user | | `timeout_member` | Timeout (mute) a member for a duration | | `set_nickname` | Set or reset a member's nickname | | **Threads** | | | `create_thread` | Create a thread in a text channel | | `list_threads` | List active and archived threads | | `archive_thread` | Archive a thread (optionally lock it) | | `unarchive_thread` | Unarchive a thread | | `join_thread` | Make the bot join a thread | | `delete_thread` | Delete a thread | --- ## Install from Source (for contributors) If you want to modify the code or run the standalone bot: ```bash 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: ```json { "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: ```bash # Register commands (one time) npm run deploy-commands # Start the bot npm run bot ``` | Command | Description | |---------|-------------| | `/ping` | Check bot latency | | `/info` | Show bot uptime and stats | | `/serverinfo` | Show server details | --- ## 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: ```bash docker-compose up -d # Start in background docker-compose logs -f # View logs ``` --- ## Architecture

mcp-discord-bridge architecture diagram

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`](https://github.com/iprashantraj/mcp-discord-bridge/blob/HEAD/assets/architecture.excalidraw) โ€” open it at [excalidraw.com](https://excalidraw.com). --- ## Development ```bash 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: ```json "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](https://github.com/iprashantraj/mcp-discord-bridge/blob/HEAD/SECURITY.md) for the full threat model and reporting policy --- ## License [MIT](https://github.com/iprashantraj/mcp-discord-bridge/blob/HEAD/LICENSE) โ€” use it however you want.