@devli13/mcp-discord

@devli13/mcp-discord

An MCP server for Discord. Send messages, moderate, manage channels, inspect servers — from Claude Code, Paperclip agents, Gemini CLI, or any MCP-compatible client.

Pure REST wrapper. No Gateway. No database. Just Discord's v10 API as 26 well-documented tools, with per-route rate limiting and structured error results.

Why

Discord's API is sprawling and agent-unfriendly when called via raw curl. Agents hit rate limits, mishandle 429s, fumble audit-log reasons, forget pagination cursors. This MCP fixes that once, so agents can focus on intent: "delete that spam message," "post the daily digest to #mod-log," "timeout @user for an hour."

Also great for humans. Connected to Claude Code, you can say "summarize the last 50 messages in my Discord #dev channel" and Claude just does it.

Install

npm install -g @devli13/mcp-discord

Or via npx (no install):

DISCORD_BOT_TOKEN=<your-token> npx -y @devli13/mcp-discord

Setup

1. Create a Discord bot

1. Go to https://discord.com/developers/applications → New Application
2. Add a Bot to the application
3. Copy the bot token — this is your DISCORD_BOT_TOKEN
4. Invite the bot to your server using the OAuth2 URL generator (scope: bot). Pick permissions based on what you need the MCP to do (e.g. Manage Messages for deletes, Moderate Members for timeouts)

2. Wire it to your MCP client

Claude Code:

claude mcp add discord \
  --env DISCORD_BOT_TOKEN=<your-token> \
  -- npx -y @devli13/mcp-discord

Paperclip mcp-gateway (.mcp.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"],
      "env": {
        "DISCORD_BOT_TOKEN": "<your-token>"
      }
    }
  }
}

Gemini CLI (~/.gemini/config.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"]
    }
  }
}

3. (Optional) Enable privileged intents

If you want to list server members (discord_list_members) or use this MCP alongside the companion plugin for inbound events, enable Server Members Intent and Message Content Intent in your bot's Developer Portal settings. These are not required for most MCP operations — only for specific endpoints.

Tool reference

All tools are prefixed discord_* and return either a JSON blob (on success) or a formatted error message (on failure). None throw — every tool returns a usable string result.

Messages (8)

Reactions (3)

Channels & Threads (5)

Moderation (6)

Server info (4)

Not included (by design):

• ban/unban — deliberate. Use Discord's UI; irreversible actions shouldn't be one agent-call away
• Channel create/delete/edit — high blast radius, use the UI
• Webhook CRUD — not needed for most agent flows; can add in a future release
• Voice operations, sticker/emoji management — out of scope for v0.1

Example: summarize a channel via Claude Code

User: Summarize the last 30 messages in the #dev channel of my Discord server, guild ID 1234...

Claude (calls discord_list_channels → finds #dev → calls discord_list_messages → writes summary)

Example: Paperclip agent daily digest

// From an agent's prompt:
"Post the daily digest to channel 1234. Summarize the last 24h of activity
using discord_list_messages with limit=100, then format as an embed via
discord_send_message."

Error handling

Every tool returns a usable text result. On error:

Error (DISCORD_50001, HTTP 403): Missing Access
Details: [...]
(This error is transient and may succeed on retry.)

The MCP already handles retries internally for 429 (rate limits) and 5xx (server errors), with exponential backoff.

Rate limits

Discord has two rate-limit layers:

1. Per-route — each API endpoint has independent buckets. This MCP serializes requests per (method + route template) to prevent bursting past a 429.
2. Global — per-bot, across all endpoints. The MCP honors Retry-After headers globally.

You shouldn't need to think about this. If you do hit the global limit repeatedly, you're probably doing something that deserves a human in the loop.

Security

• Never commit your bot token. This MCP reads it from DISCORD_BOT_TOKEN environment variable at startup.
• Use least-privilege invite URLs. Don't give bots Administrator if you only need Manage Messages.
• Audit log reasons — all moderation tools accept a reason argument that appears in Discord's audit log. Use it.

Development

git clone https://github.com/devli13/mcp-discord.git
cd mcp-discord
npm install
npm test           # smoke tests (no live Discord calls)
npm run lint       # syntax check all files
npm start          # boot server over stdio (needs DISCORD_BOT_TOKEN)

Companion project — inbound events

This MCP handles outbound REST calls (send, delete, moderate). It does not hold a Discord Gateway WebSocket, so it can't react to inbound events (a user @mentioning the bot, DMs, new members joining).

For inbound Discord events in a Paperclip setup, use @devli13/paperclip-plugin-discord — a fork of @mvanhorn/paperclip-plugin-discord with free-form @mention routing, DM support, a serialized per-context message queue, and downtime mention backfill.

The two projects are designed to work together: the plugin receives events, invokes your agent; the agent uses this MCP to respond and moderate. Use either or both depending on your setup.

Attribution

See ATTRIBUTION.md. Short version: built alongside the fork of paperclip-plugin-discord by @mvanhorn, whose Gateway handling inspired design patterns here.

License

MIT — see LICENSE.