io.github.PaSympa/discord-mcp MCP Server

<div align="center">

Discord MCP Server

A lightweight, multi-guild Discord MCP server with 95+ tools

Manage your entire Discord server from Claude Desktop, Claude Code, Cursor, VS Code Copilot, or any MCP-compatible client. Messages, channels, roles, permissions, moderation, forums, webhooks, all through natural language.

</div>

---

Why this one?

• 95+ tools: messages, channels, roles, permissions, moderation, forums, webhooks, scheduled events, invites, DMs, embeds, and more
• Multi-guild: works across multiple servers, no GUILD_ID lock-in
• Lightweight: TypeScript + Node.js, ~70kB package, ~73MB Docker image (vs 400MB+ for Java alternatives)
• Modular: clean architecture, easy to extend with new tools
• Two install methods: npm or Docker, your choice

---

Quick Start

Add this to your MCP client config and replace YOUR_TOKEN_HERE with your bot token:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@pasympa/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

No install needed, npx handles everything.

Don't have a bot yet? See Creating Your Discord Bot.

---

Configuration

<details> <summary><strong>Claude Desktop</strong></summary>

Add the config above to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after saving.

</details> <details> <summary><strong>Claude Code</strong></summary>

claude mcp add discord -e DISCORD_TOKEN=YOUR_TOKEN_HERE -- npx -y @pasympa/discord-mcp

</details> <details> <summary><strong>Cursor</strong></summary>

Add the config above to ~/.cursor/mcp.json. See Cursor MCP docs for details.

</details> <details> <summary><strong>VS Code / GitHub Copilot</strong></summary>

Add to your .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "discord-token",
      "description": "Discord Bot Token",
      "password": true
    }
  ],
  "servers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@pasympa/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "${input:discord-token}"
      }
    }
  }
}

See VS Code MCP docs for details.

</details> <details> <summary><strong>Docker</strong></summary>

{
  "mcpServers": {
    "discord": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DISCORD_TOKEN=YOUR_TOKEN_HERE",
        "pasympa/discord-mcp:latest"
      ]
    }
  }
}

</details> <details> <summary><strong>From source</strong></summary>

git clone https://github.com/PaSympa/discord-mcp
cd discord-mcp
npm install && npm run build

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp/dist/index.js"],
      "env": {
        "DISCORD_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

</details> <details> <summary><strong>.env file (alternative)</strong></summary>

Instead of passing the token in the MCP config, create a .env file at the project root:

DISCORD_TOKEN=YOUR_TOKEN_HERE

The server loads .env automatically via dotenv.

</details>

Environment variables

Variable	Default	Description
DISCORD_TOKEN	none	Required. Bot token.
DISCORD_MESSAGE_CONTENT	true	Set to false to stop requesting the Message Content privileged gateway intent at connect time.
DISCORD_GUILD_MEMBERS	true	Set to false to stop requesting the Server Members privileged gateway intent at connect time.
DISCORD_MCP_TOOLSETS	all	Comma-separated list of toolsets to expose, to keep the tool list small. Unset or all exposes every tool.
DISCORD_ALLOWED_GUILDS	all	Comma-separated guild IDs the server may act on. When set, tool calls targeting any other guild are rejected, whether addressed by guild ID, channel ID, thread ID, webhook, or invite code.

Since 2.1.1 the server no longer requests the GuildMessages intent at all: nothing here subscribes to message events, and every message this server returns is fetched over REST, which connection intents do not gate. That intent used to make discord.js cache every message flowing through every channel, together with its author, which grew unbounded on a long-running server. Cache sweepers now bound what remains. DISCORD_MESSAGE_CONTENT therefore only affects whether the Message Content intent is requested at connect time; it does not change what any tool returns.

These flags only control which gateway intents the server requests when identifying. Requesting a privileged intent that is not enabled in the Developer Portal makes the connection fail at the first tool call (close code 4014); set the flag to false to connect anyway.

Data access is governed by the portal toggles, not by these flags: this server reads everything over the REST API, which Discord gates on the portal setting alone. So with the portal toggles on, setting these flags to false loses nothing. With a portal toggle off, the corresponding data is restricted regardless of the flags: message bodies come back empty (content, embeds, attachments; except the bot's own messages, DMs, and messages that mention the bot) and member listing fails; enable the toggle in the portal to restore it.

Toolsets (DISCORD_MCP_TOOLSETS): discovery, messages, channels, permissions, members, roles, moderation, screening, stats, forums, webhooks, scheduled_events, invites, dm. Example; DISCORD_MCP_TOOLSETS=discovery,messages,members exposes only the discovery, message, and member tools. Note: a toolset ships its whole module, including its destructive tools (messages includes bulk delete; members includes kick/ban); use DISCORD_ALLOWED_GUILDS and the dry-run defaults to bound them. Only the listed toolsets' tools are advertised and callable. Unknown names make the server fail at startup instead of silently exposing everything (an empty value counts as unset and exposes all).

---

Creating Your Discord Bot

1. Go to discord.com/developers/applications

2. New Application > give it a name

3. Bot tab > Reset Token > copy the token

4. Enable Privileged Gateway Intents (this server requests both by default, but new Discord apps have the portal toggles OFF):

   • Server Members Intent
   • Message Content Intent

   Important: if the bot requests a privileged intent that is not enabled here, Discord closes the connection with code 4014 and every tool call fails. Enable both, or stop requesting the ones you don't need via the environment variables above.

5. OAuth2 > URL Generator:

   • Scopes: bot
   • Permissions: Send Messages, Read Message History, Manage Channels, Manage Roles, Kick Members, Ban Members, Moderate Members, View Audit Log, Manage Messages, Manage Threads, Add Reactions, Manage Guild, Manage Webhooks, Manage Events, Create Events, Create Instant Invite, Manage Nicknames, Pin Messages, Embed Links, Create Public Threads, Send Messages in Threads

6. Copy the generated URL and invite the bot to your server

---

Available Tools (99)

Discovery & Navigation (4 tools)

Tool	Description
discord_list_guilds	List all servers the bot is connected to
discord_get_guild_info	Get detailed guild info (name, members, channels, roles, boosts)
discord_list_channels	List all channels in a guild grouped by category
discord_find_channel_by_name	Find a channel by name (partial match)

Messages (20 tools)

Tool	Description
discord_read_messages	Read messages, paging back through history
discord_send_message	Send a plain text message
discord_reply_message	Reply to a specific message
discord_edit_message	Edit a message sent by the bot
discord_delete_message	Delete a specific message
discord_add_reaction	Add a reaction emoji to a message
discord_remove_reactions	Remove reactions (all, by emoji, or by user)
discord_get_reactions	List users who reacted with a specific emoji
discord_create_thread	Create a thread from a message or standalone
discord_bulk_delete_messages	Delete multiple messages at once (2-100)
discord_send_embed	Send a rich embed with all options
discord_edit_embed	Edit an embed previously sent by the bot
discord_send_multiple_embeds	Send up to 10 embeds in a single message
discord_pin_message	Pin or unpin a message
discord_get_message_attachments	List a message's attachments with download urls
discord_fetch_pinned_messages	List all pinned messages in a channel
discord_search_messages	Search messages by keyword (last 100)
discord_search_guild_messages	Search across every channel using Discord's search index
discord_crosspost_message	Publish a message to announcement channel followers
discord_forward_message	Forward a message to another channel

Channels (8 tools)

Tool	Description
discord_create_channel	Create a text, voice channel or category
discord_delete_channel	Delete a channel
discord_edit_channel	Edit name, topic, slowmode, NSFW flag
discord_move_channel	Move a channel into/out of a category
discord_clone_channel	Clone a channel with its permissions
discord_set_channel_position	Set display position within a category
discord_follow_announcement_channel	Follow an announcement channel
discord_lock_channel_permissions	Sync permissions with parent category

Channel Permissions (6 tools)

Tool	Description
discord_get_channel_permissions	List all permission overwrites on a channel
discord_set_role_permission	Allow/deny permissions for a role on a channel
discord_set_member_permission	Allow/deny permissions for a member on a channel
discord_reset_channel_permissions	Remove all overwrites (reset to inherited)
discord_copy_permissions	Copy overwrites from one channel to another
discord_audit_permissions	Full permission audit for all channels

Members (11 tools)

Tool	Description
discord_list_members	List guild members with their roles
discord_get_member_info	Detailed member info (roles, permissions, join date)
discord_search_members	Search members by username or nickname
discord_set_nickname	Set or clear a member's nickname
discord_kick_member	Kick a member
discord_ban_member	Ban a member (optionally delete recent messages)
discord_unban_member	Unban a user
discord_bulk_ban	Ban multiple users at once (raid mitigation)
discord_list_bans	List all banned users
discord_timeout_member	Timeout a member (0 to remove)
discord_prune_members	Remove inactive members (with dry run)

Roles (9 tools)

Tool	Description
discord_list_roles	List all roles with permissions and member count
discord_create_role	Create a new role
discord_edit_role	Edit a role (name, color, permissions, hoist, mentionable)
discord_delete_role	Delete a role
discord_add_role	Assign a role to a member
discord_remove_role	Remove a role from a member
discord_get_role_members	List all members with a specific role
discord_set_role_position	Change a role's position in the hierarchy
discord_set_role_icon	Set a custom icon or unicode emoji on a role

Forums (10 tools)

Tool	Description
discord_get_forum_channels	List all forum channels in a guild
discord_create_forum_channel	Create a new forum channel
discord_create_forum_post	Create a post/thread in a forum
discord_get_forum_post	Get a post's details and messages
discord_list_forum_threads	List threads (active + archived)
discord_reply_to_forum	Reply to a forum post
discord_delete_forum_post	Delete a forum thread
discord_get_forum_tags	Get available tags
discord_set_forum_tags	Set/update tags on a forum
discord_update_forum_post	Update title, archived, locked, tags

Webhooks (8 tools)

Tool	Description
discord_create_webhook	Create a webhook on a channel
discord_send_webhook_message	Send via webhook (custom username/avatar, embeds)
discord_edit_webhook	Edit a webhook's name, avatar, or channel
discord_delete_webhook	Delete a webhook
discord_list_webhooks	List webhooks for a channel or guild
discord_edit_webhook_message	Edit a message sent by a webhook
discord_delete_webhook_message	Delete a message sent by a webhook
discord_fetch_webhook_message	Fetch a specific webhook message

Scheduled Events (7 tools)

Tool	Description
discord_list_scheduled_events	List all scheduled events in a guild
discord_get_scheduled_event	Get detailed info about a scheduled event
discord_create_scheduled_event	Create a voice, stage, or external event
discord_edit_scheduled_event	Edit an existing scheduled event
discord_delete_scheduled_event	Delete a scheduled event
discord_get_event_subscribers	Get users who marked "Interested"
discord_create_event_invite	Create an invite linked to an event

Direct Messages (7 tools)

Tool	Description
discord_send_dm	Send a direct message to a user by their user ID
discord_send_dm_embed	Send an embed in a DM to a user
discord_read_dms	Read message history from a DM conversation
discord_reply_dm	Reply to a specific DM message
discord_edit_dm	Edit a previously sent DM (text)
discord_edit_dm_embed	Edit a previously sent DM embed
discord_delete_dm	Delete a DM message

Invites (5 tools)

Tool	Description
discord_list_invites	List all active invites in a guild
discord_list_channel_invites	List invites for a specific channel
discord_get_invite	Get details about an invite by its code
discord_create_invite	Create an invite link for a channel
discord_delete_invite	Revoke an invite

Moderation & Screening (3 tools)

Tool	Description
discord_get_audit_log	Fetch the guild audit log
discord_get_membership_screening	Get the membership screening form
discord_update_membership_screening	Update screening rules for new members

Stats (1 tool)

Tool	Description
discord_get_server_stats	Server stats: members, channels, roles, boost level

---

Usage Examples

"List all servers the bot is in"
"Read the last 10 messages in #general"
"Send 'Hello everyone!' to the announcements channel"
"Create a forum channel called 'feedback' with tags Bug, Feature, Question"
"Show the full permission audit for the server"
"Create a webhook on #notifications and send a test message"
"Ban user 112233445566778899 and delete their messages from the last 3 days"
"Create an event called 'Game Night' for next Friday at 8pm"
"List all upcoming events in the server"
"Create a permanent invite for #general"
"List all active invites and delete expired ones"
"Send a DM to user 112233445566778899 saying 'Your build passed!'"
"Search for members named 'john'"
"List all banned users in the server"
"Show all pinned messages in #general"
"Forward that message to #announcements"

---

Finding Discord IDs

Enable Developer Mode in Discord: Settings > Advanced > Developer Mode

Then right-click on a server, channel, or user > Copy ID.

---

Project Structure

discord-mcp/
├── src/
│   ├── index.ts             ← Entry point (MCP server + transport)
│   ├── client.ts            ← Discord client + shared helpers
│   ├── constants.ts         ← Shared constants (limits, defaults)
│   ├── embeds.ts            ← Shared embed schema + builder
│   └── tools/
│       ├── index.ts         ← Tool registry (toolset gating, dispatch)
│       ├── define.ts        ← defineTool/defineModule + shared zod fields
│       ├── types.ts         ← Shared TypeScript interfaces
│       ├── discovery.ts     ← Guild/channel discovery
│       ├── messages.ts      ← Message CRUD, reactions, threads, embeds
│       ├── channels.ts      ← Channel management
│       ├── permissions.ts   ← Permission overwrites
│       ├── members.ts       ← Member management
│       ├── roles.ts         ← Role CRUD and assignment
│       ├── moderation.ts    ← Audit log
│       ├── screening.ts     ← Membership screening
│       ├── stats.ts         ← Server statistics
│       ├── forums.ts        ← Forum channels, posts, tags
│       ├── webhooks.ts      ← Webhook management
│       ├── scheduledEvents.ts ← Scheduled events
│       ├── invites.ts        ← Invite management
│       └── dm.ts             ← Direct messages
├── test/                     ← node:test suite (schemas, gating, allow-list)
├── scripts/                  ← sync-version.js (npm version hook)
├── .github/workflows/        ← CI/CD (build check + auto release)
├── Dockerfile
├── .dockerignore
├── .env.example
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── README.md

Adding a new tool

1. Create a new file in src/tools/ (e.g. events.ts)
2. Declare each tool with defineTool({ name, description, annotations, schema, handle }) and export defineModule([...]) as the default
3. Import it and add it to allToolsets in src/tools/index.ts (the key is its DISCORD_MCP_TOOLSETS name)

---

Security

• Never commit your Discord token to Git
• Use environment variables or a .env file (not versioned)
• Give the bot only the permissions it needs
• Restrict the server to specific servers with DISCORD_ALLOWED_GUILDS
• Irreversible mass actions (bulk_ban, prune_members, bulk_delete_messages, delete_channel) default to a dry_run preview; pass dry_run:false to apply

---

Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Follow the modular structure, see Adding a new tool
4. Commit your changes and open a pull request

---

License

MIT, see LICENSE for details.