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)

Channels (7 tools)

Messages (8 tools)

Reactions (2 tools)

Members / Users (4 tools)

Roles (4 tools)

Moderation (4 tools)

Monitoring (2 tools)

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

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.