@devli13/mcp-discord

一个用于 Discord 的 MCP 服务器。通过 Claude Code、Paperclip 代理、Gemini CLI 或任何兼容 MCP 的客户端，发送消息、进行审核、管理频道、检查服务器。

纯 REST 封装。无网关。无数据库。 仅将 Discord v10 API 封装为 26 个文档齐全的工具，并提供按路由的速率限制和结构化的错误结果。

为什么选择它

Discord 的 API 非常庞大，且通过原始 curl 调用时对代理不友好。代理经常遇到速率限制、无法处理 429 错误、搞砸审计日志原因、忘记分页游标。此 MCP 一次性解决了这些问题，让代理可以专注于意图：“删除那条垃圾消息”、“将每日摘要发布到 #mod-log”、“禁言 @user 一小时”。

它也非常适合人类使用。连接到 Claude Code 后，你可以说*“总结我在 Discord #dev 频道中的最后 50 条消息”*，Claude 就能直接完成。

Related MCP server: Discord Bridge MCP Server

安装

npm install -g @devli13/mcp-discord

或者通过 npx（无需安装）：

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

设置

1. 创建一个 Discord 机器人

1. 前往 https://discord.com/developers/applications → New Application

2. 为应用程序添加一个 Bot

3. 复制机器人令牌 — 这就是你的 DISCORD_BOT_TOKEN

4. 使用 OAuth2 URL 生成器（范围：bot）将机器人邀请到你的服务器。根据你需要 MCP 执行的操作选择权限（例如：管理消息以进行删除，管理成员以进行禁言）

2. 将其连接到你的 MCP 客户端

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. (可选) 启用特权意图

如果你想列出服务器成员 (discord_list_members) 或将此 MCP 与配套插件一起用于入站事件，请在机器人的开发者门户设置中启用 Server Members Intent 和 Message Content Intent。大多数 MCP 操作不需要这些权限 — 仅特定端点需要。

工具参考

所有工具均以 discord_* 为前缀，并返回 JSON 数据块（成功时）或格式化的错误消息（失败时）。没有任何工具会抛出异常 — 每个工具都会返回一个可用的字符串结果。

消息 (8)

反应 (3)

频道与线程 (5)

审核 (6)

服务器信息 (4)

未包含（有意为之）：

• ban/unban — 刻意为之。请使用 Discord UI；不可逆的操作不应通过一次代理调用完成

• 频道创建/删除/编辑 — 影响范围太大，请使用 UI

• Webhook CRUD — 大多数代理流程不需要；可在未来版本中添加

• 语音操作、贴纸/表情符号管理 — 超出 v0.1 的范围

示例：通过 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)

示例：Paperclip 代理每日摘要

// 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 (DISCORD_50001, HTTP 403): Missing Access
Details: [...]
(This error is transient and may succeed on retry.)

该 MCP 已在内部处理了 429（速率限制）和 5xx（服务器错误）的重试，并带有指数退避策略。

速率限制

Discord 有两层速率限制：

1. 按路由 — 每个 API 端点都有独立的桶。此 MCP 会按（方法 + 路由模板）序列化请求，以防止超过 429 限制。

2. 全局 — 每个机器人，跨所有端点。此 MCP 全局遵循 Retry-After 标头。

你不需要考虑这些。如果你反复触及全局限制，你可能正在做一些需要人工介入的事情。

安全性

• 永远不要提交你的机器人令牌。 此 MCP 在启动时从 DISCORD_BOT_TOKEN 环境变量中读取它。

• 使用最小权限的邀请 URL。 如果你只需要“管理消息”，就不要给机器人“管理员”权限。

• 审计日志原因 — 所有审核工具都接受一个 reason 参数，该参数会出现在 Discord 的审计日志中。请使用它。

开发

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)

配套项目 — 入站事件

此 MCP 处理出站 REST 调用（发送、删除、审核）。它不持有 Discord 网关 WebSocket，因此无法响应入站事件（用户 @提及机器人、私信、新成员加入）。

对于 Paperclip 设置中的入站 Discord 事件，请使用 @devli13/paperclip-plugin-discord — 它是 @mvanhorn/paperclip-plugin-discord 的一个分支，具有自由格式的 @提及路由、私信支持、序列化的每上下文消息队列以及停机期间的提及补发功能。

这两个项目旨在协同工作：插件接收事件并调用你的代理；代理使用此 MCP 进行响应和审核。根据你的设置，可以使用其中一个或两个。

归属

请参阅 ATTRIBUTION.md。简而言之：与 @mvanhorn 的 paperclip-plugin-discord 分支一起构建，其网关处理方式启发了此处的架构模式。

许可证

MIT — 请参阅 LICENSE。