discord-mcp-server

A Model Context Protocol (MCP) server that exposes Discord operations as tools for AI assistants.

---

What is this?

discord-mcp-server lets any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) interact with Discord — send messages, manage channels, create webhooks, assign roles, and more.

Built with Bun, FastMCP, and discord.js.

Features

Category	Tools
🏠 Server Info	list_servers, get_server_info
📢 Channels	list_channels, find_channel, create_text_channel, create_voice_channel, delete_channel, create_category, list_categories, move_channel
💬 Messages	send_message, read_messages, edit_message, delete_message, add_reaction, remove_reaction
🔗 Webhooks	list_webhooks, create_webhook, delete_webhook, send_webhook_message, edit_webhook
🎭 Roles	list_roles, create_role, edit_role, delete_role, assign_role, remove_role
🧵 Threads	list_threads, create_thread, reply_to_thread, get_thread

31 tools covering the most common Discord operations. Forum posts are supported via create_thread.

Prerequisites

1. Bun (v1.0.0+) — Install Bun
2. Discord Bot Token — Create one here

Creating a Discord Bot

1. Go to the Discord Developer Portal
2. Click New Application → give it a name
3. Go to Bot → click Reset Token → copy the token
4. Under Privileged Gateway Intents, enable:
   • ✅ Message Content Intent
   • ✅ Server Members Intent
5. Go to OAuth2 → URL Generator
   • Scopes: bot
   • Bot Permissions: Administrator (or cherry-pick permissions)
6. Copy the generated URL and open it to invite the bot to your server

Quick Start

Option 1: npx (recommended)

npx @ncodelife/discord-mcp-server --token YOUR_BOT_TOKEN

Option 2: Install globally

npm install -g @ncodelife/discord-mcp-server
discord-mcp-server --token YOUR_BOT_TOKEN

Option 3: Docker

docker build -t discord-mcp-server .
docker run -e DISCORD_TOKEN=YOUR_BOT_TOKEN discord-mcp-server

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["@ncodelife/discord-mcp-server", "--token", "YOUR_BOT_TOKEN"]
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "discord": {
    "command": "npx",
    "args": ["@ncodelife/discord-mcp-server", "--token", "YOUR_BOT_TOKEN"]
  }
}

Smithery

Install via Smithery for automatic configuration.

Configuration

Option	CLI Flag	Env Variable	Default
Bot Token	--token	DISCORD_TOKEN	required
Default Guild ID	--guild-id	DISCORD_GUILD_ID	—
Transport	--transport	MCP_TRANSPORT	stdio
HTTP Port	--port	MCP_PORT	8080

Using a .env file

DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD_ID=your-server-id

Transport Modes

stdio (default)

Standard I/O transport — used by Claude Desktop, Cursor, and most MCP clients.

discord-mcp-server --token YOUR_TOKEN

HTTP Stream

For web-based integrations and remote access:

discord-mcp-server --token YOUR_TOKEN --transport http --port 8080

Note on build targets: The npm package is built with --target node so npx works everywhere. The Docker image uses --target bun for native Bun performance. Both are fully functional.

Development

# Clone the repo
git clone https://github.com/ngoctranfire/discord-mcp-server.git
cd discord-mcp-server

# Install dependencies
bun install

# Run in development
bun run dev

# Type-check
bun run typecheck

# Lint
bun run lint

# Test with MCP Inspector
bun run inspect

Architecture

src/
├── index.ts          # Entry point — FastMCP server setup
├── config.ts         # CLI args + env var merging
├── discord.ts        # Discord.js client factory
├── utils.ts          # Shared utilities (error handling, formatting)
└── tools/
    ├── server-info.ts  # Server listing & details
    ├── channels.ts     # Channel CRUD operations
    ├── messages.ts     # Message send/read/edit/delete + reactions
    ├── webhooks.ts     # Webhook management
    ├── roles.ts        # Role CRUD + assignment
    └── threads.ts      # Thread & forum operations

Contributing

See CONTRIBUTING.md for guidelines on setup, development, and submitting pull requests.

License

MIT