mcp-discord

The most complete open-source MCP server for Discord.

Give any MCP client (Claude, Cursor, custom agents) full control over Discord — messages, moderation, channels, roles, and more. Born from production use at delfus.app, open-sourced for the community.

Portugues (BR)

Why mcp-discord?

• 30+ tools across 8 categories — servers, channels, messages, reactions, members, roles, moderation, and monitoring
• Dual-mode — run standalone (own process) or integrate as a plugin into your existing discord.js bot
• REST-only or Gateway — choose between lightweight REST-only mode or full WebSocket gateway for real-time features
• Two transports — stdio (default, for Claude Desktop / Claude Code) or HTTP with Bearer token auth
• Production-proven — built and used in production at delfus.app

Quick Start

Prerequisites

• Node.js 18 or higher
• A Discord bot token

Install

# Clone the repository
git clone https://github.com/goul4rt/mcp-discord.git
cd mcp-discord

# Install dependencies
npm install

# Build
npm run build

Configure

cp .env.example .env

Edit .env and add your Discord bot token:

DISCORD_TOKEN=your-bot-token-here

Run

# stdio transport (default — for MCP clients like Claude)
npm start

# HTTP transport (for remote/web clients)
npm run start:http

MCP Client Configuration

Claude Desktop / Claude Code

Add to your MCP config file:

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here"
            }
        }
    }
}

With Gateway (real-time features)

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here",
                "DISCORD_USE_GATEWAY": "true"
            }
        }
    }
}

Tools

Server / Guild (2 tools)

| Tool | Description | |------|-------------| | list_servers | List all Discord servers the bot has access to | | get_server_info | Get detailed info about a specific server |

Channels (7 tools)

| Tool | Description | |------|-------------| | get_channels | List all channels in a server | | get_channel | Get detailed info about a channel | | create_channel | Create text, voice, category, announcement, forum, or stage channels | | edit_channel | Edit channel name, topic, NSFW, slowmode, position, category | | delete_channel | Permanently delete a channel | | create_thread | Create a thread in a channel (optionally from a message) | | archive_thread | Archive a thread |

Messages (8 tools)

| Tool | Description | |------|-------------| | send_message | Send messages with text, rich embeds, and replies | | read_messages | Read recent messages with pagination (up to 100) | | search_messages | Search messages by content, author, or channel | | edit_message | Edit a bot message | | delete_message | Delete a single message | | delete_messages_bulk | Bulk delete 2-100 messages (< 14 days old) | | pin_message | Pin a message | | unpin_message | Unpin a message |

Reactions (2 tools)

| Tool | Description | |------|-------------| | add_reaction | Add emoji reaction (Unicode or custom) | | remove_reaction | Remove a reaction |

Members / Users (4 tools)

| Tool | Description | |------|-------------| | list_members | List server members with pagination | | get_member | Get detailed member info (roles, nickname, join date) | | get_user | Get info about any Discord user by ID | | search_members | Search members by username or nickname |

Roles (4 tools)

| Tool | Description | |------|-------------| | list_roles | List all roles with permissions, colors, and member counts | | create_role | Create a new role | | add_role | Add a role to a member | | remove_role | Remove a role from a member |

Moderation (4 tools)

| Tool | Description | |------|-------------| | timeout_user | Temporarily mute a user (up to 28 days) | | kick_user | Kick a user from the server | | ban_user | Ban a user with optional message deletion | | unban_user | Unban a user |

Monitoring (2 tools)

| Tool | Description | |------|-------------| | get_audit_log | View server audit log (bans, kicks, changes) | | check_mentions | Find recent @mentions of the bot or a user |

Architecture

┌─────────────────────────────────────────────────┐
│                  MCP Client                      │
│          (Claude, Cursor, custom)                │
└──────────────────┬──────────────────────────────┘
                   │ stdio or HTTP
┌──────────────────▼──────────────────────────────┐
│               MCP Server                         │
│         (transport + tool routing)                │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│            Tool Registry                         │
│         (30 tools, Zod validation)               │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│          DiscordProvider (interface)              │
├─────────────────────┬───────────────────────────┤
│ StandaloneProvider  │  IntegratedProvider        │
│ (own token + REST/  │  (uses host bot's          │
│  optional gateway)  │   existing connection)      │
└─────────────────────┴───────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│              Discord API                         │
└─────────────────────────────────────────────────┘

Provider abstraction: MCP tools never touch discord.js directly. They call the DiscordProvider interface, which has two implementations:

• StandaloneProvider — creates its own connection using a bot token. REST-first with optional gateway. Use when running as a separate process.
• IntegratedProvider — receives an existing discord.js Client from the host bot. Zero overhead, shared cache and gateway. Use when embedding in an existing bot.

Integration Guide

To use mcp-discord as a plugin inside your existing discord.js bot:

import { IntegratedProvider, createMcpServer } from 'mcp-discord';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Your existing discord.js client
const provider = new IntegratedProvider({ client: myDiscordClient });
await provider.connect();

const server = createMcpServer({ provider });
const transport = new StdioServerTransport();
await server.connect(transport);

The IntegratedProvider uses your bot's existing gateway connection — no extra WebSocket, no extra authentication, no extra memory.

Configuration Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DISCORD_TOKEN | Yes | — | Discord bot token | | DISCORD_USE_GATEWAY | No | false | Connect to Discord WebSocket gateway for real-time features | | MCP_TRANSPORT | No | stdio | Transport mode: stdio or http | | MCP_PORT | No | 3100 | HTTP server port (only when MCP_TRANSPORT=http) | | MCP_AUTH_TOKEN | No | — | Bearer token for HTTP transport authentication |

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, code style, and how to add new tools.

License

MIT

Author

Created by @goul4rt. Born from delfus.app, open-sourced for the community.