内容
# Discord MCP 服务器
一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，用于将 Claude（或任何 MCP 客户端）连接到您管理的 Discord 服务器。它提供了 53 种工具，涵盖日常管理任务：频道、线程、角色、成员、审核、AutoMod、消息、投票、Webhook、预定活动、邀请、审核日志和实时事件日志——以及现成的审核和报告提示。
使用 TypeScript、[discord.js](https://discord.js.org) v14 和官方 [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) 构建。默认使用现代 **Streamable HTTP** 传输（会话，适用于远程托管），并为本地启动服务器的客户端提供_stdio 回退。
## 功能
- **实时事件日志** — 服务器实时记录网关事件（加入、离开、封禁、消息删除/编辑、角色和频道更改），因此 Claude 可以回答“我在离开时服务器发生了什么？”
- **服务器** — 列出您的服务器，检查服务器详细信息，读取审核日志
- **频道** — 列出、创建、编辑和删除频道/类别；设置按角色或按用户的权限覆盖；慢速模式、NSFW、话题
- **线程和论坛** — 列出活动/存档线程，创建线程和论坛帖子，存档/锁定/重命名
- **AutoMod** — 创建、编辑、列出和删除 Discord 的原生 AutoMod 规则：关键词过滤器、正则表达式、垃圾信息和提及垃圾信息阻止、内置脏话/侮辱词列表，具有阻止/提醒/超时操作
- **角色** — 列出、创建、编辑和删除角色；分配或从成员中删除
- **成员** — 列出和搜索成员，查看详细信息，设置昵称，超时，踢出，封禁，解除封禁，列出封禁
- **权限审核** — 计算有效访问报告：谁可以查看/发布到频道以及为什么，以及一个成员可以在服务器范围内或按频道执行什么操作
- **消息** — 读取历史记录，发送（带有回复和嵌入），编辑，删除，批量删除，固定/取消固定，添加反应，创建原生投票
- **Webhook** — 创建、列出和删除 Webhook；通过它们发送消息，带有按消息的名称/头像覆盖
- **预定活动** — 创建、编辑、启动/完成/取消和删除服务器活动（语音、舞台或外部）
- **邀请** — 创建带有过期/使用限制的邀请链接，列出活动邀请
- **提示** — `server_health_audit` 和 `moderation_report` 通过一个命令引导 Claude 完成多步骤管理工作流
### 默认安全
- **破坏性工具默认关闭。** 踢出、封禁、批量删除和每个删除工具（频道、角色、消息、AutoMod 规则、Webhook、预定活动）拒绝运行，除非服务器使用 `DISCORD_ENABLE_DESTRUCTIVE=true` 启动——它们是下面表格中标记为 † 的工具。
- **服务器允许列表。** 将 `DISCORD_GUILD_IDS` 设置为以逗号分隔的服务器 ID 列表，并且所有工具都局限于这些服务器，即使机器人恰好在其他服务器中。
- **审核日志原因。** 审核和管理工具接受一个 `reason`，记录在 Discord 的审核日志中，适用于 Discord 支持的日志（消息删除/批量删除除外）。
- **只读/破坏性注释。** 工具带有 MCP 注释，以便客户端可以应用其自己的确认策略。
## 安装
### 1. 创建 Discord 机器人
1. 进入 [Discord 开发者门户](https://discord.com/developers/applications) 并点击 **新建应用程序**。
2. 在 **机器人** 下，点击 **重置令牌** 并复制令牌 — 这成为 `DISCORD_TOKEN`。
3. 仍然在 **机器人 → 特权网关意图** 下，启用 **服务器成员意图** 和 **消息内容意图**。（如果您跳过此步骤，请设置 `DISCORD_PRIVILEGED_INTENTS=false`；成员列表和消息内容将不可用。）
### 2. 将机器人邀请到您的服务器
在 **OAuth2 → URL 生成器** 下，选择 `bot` 范围，然后选择机器人具有的权限（对于完整的管理工具：管理频道、管理角色、踢出成员、封禁成员、调节成员、管理消息、读取消息历史、发送消息、查看审核日志、创建即时邀请）。打开生成的 URL 并将机器人添加到您的服务器。
机器人永远不会执行超过您授予它的权限 — 如果缺少权限，工具会以清晰的错误提示失败。
### 3. 构建
```bash
npm install
npm run build
```
### 4. 运行服务器
```bash
DISCORD_TOKEN=your-bot-token npm start
# [discord-mcp] Streamable HTTP 服务器监听 http://127.0.0.1:3000/mcp
```
服务器在 `http://127.0.0.1:3000/mcp` 处公开 MCP 端点和一个 `GET /health` 探测器。设置 `MCP_AUTH_TOKEN` 以要求一个 bearer 令牌，您应该始终在服务器可以被除您以外的任何人访问时执行此操作。
### 5. 添加到您的 MCP 客户端
**Claude 代码：**
```bash
claude mcp add --transport http discord http://127.0.0.1:3000/mcp \
--header "Authorization: Bearer your-mcp-auth-token"
```
**Claude Desktop / claude.ai 自定义连接器：** 添加一个指向 `http(s)://your-host:3000/mcp` 的远程 MCP 服务器。对于 claude.ai，服务器必须可以从互联网通过 HTTPS 访问（将其放在 Caddy 或 nginx 等反向代理后面，并设置 `MCP_ALLOWED_HOSTS` 为您的公共主机名）。
**仅启动本地_stdio 服务器的客户端** 仍然可以使用 `MCP_TRANSPORT=stdio`:
```json
{
"mcpServers": {
"discord": {
"command": "node",
"args": ["/absolute/path/to/Discord-MCP/dist/index.js"],
"env": {
"DISCORD_TOKEN": "your-bot-token",
"MCP_TRANSPORT": "stdio"
}
}
}
}
```
然后询问类似“列出我的 Discord 服务器”或“我的服务器有哪些频道？”的问题。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `DISCORD_TOKEN` | 是 | — | 来自开发者门户的机器人令牌 |
| `DISCORD_GUILD_IDS` | 否 | 所有服务器 | 以逗号分隔的服务器 ID 允许列表，工具可以触及 |
| `DISCORD_ENABLE_DESTRUCTIVE` | 否 | `false` | `true` 解锁九个 †-标记的破坏性工具（踢出、封禁、批量删除和每个删除） |
| `DISCORD_PRIVILEGED_INTENTS` | 否 | `true` | `false` 在没有服务器成员/消息内容特权意图的情况下登录 |
| `MCP_TRANSPORT` | 否 | `http` | `http`（Streamable HTTP）或 `stdio` |
| `MCP_PORT`（或 `PORT`） | 否 | `3000` | HTTP 端口 |
| `MCP_HOST` | 否 | `127.0.0.1` | 绑定地址；远程托管时使用 `0.0.0.0` |
| `MCP_AUTH_TOKEN` | 否 | — | 设置时，请求必须发送 `Authorization: Bearer <token>` |
| `MCP_ALLOWED_HOSTS` | 否 | 本地主机变体 | 主机头允许列表（DNS 重新绑定保护），在公共地址上托管时 |
### 传输安全
- 在默认的环回绑定上，DNS 重新绑定保护自动启用：请求的主机头不是本地主机变体的请求会被拒绝，返回 403，因此恶意网页无法从您的浏览器访问服务器。
- 绑定到非环回地址而没有 `MCP_AUTH_TOKEN` 会记录大声警告——任何可以访问端口的人都可以管理您的 Discord 服务器。
- 会话遵循 Streamable HTTP 规范：客户端在初始化时接收 `Mcp-Session-Id`，在每个请求上呈现它，并且可以使用 `DELETE /mcp` 终止会话。
## 工具
| 工具 | 描述 |
| --- | --- |
| `discord_list_servers` | 列出机器人可以管理的服务器 |
| `discord_get_server_info` | 服务器详细信息、计数、提升等级 |
| `discord_get_audit_log` | 最近的审核日志条目，按操作筛选 |
| `discord_list_channels` | 所有频道和类别及其 ID |
| `discord_create_channel` | 创建文本/语音/类别/公告/论坛/舞台频道 |
| `discord_edit_channel` | 重命名、重新主题、慢速模式、NSFW、移动、重新分类 |
| `discord_delete_channel` † | 永久删除频道 |
| `discord_set_channel_permissions` | 允许/拒绝角色或用户的权限覆盖 |
| `discord_list_roles` | 所有角色及其权限，按优先级排序 |
| `discord_create_role` | 创建角色（颜色、权限、提升、提及） |
| `discord_edit_role` | 编辑角色 |
| `discord_delete_role` † | 永久删除角色 |
| `discord_add_role_to_member` | 给成员一个角色 |
| `discord_remove_role_from_member` | 从成员中删除角色 |
| `discord_list_members` | 列出成员（需要服务器成员意图） |
| `discord_search_members` | 按名称前缀搜索成员 |
| `discord_get_member` | 成员详细信息、角色、权限 |
| `discord_set_nickname` | 设置或清除昵称 |
| `discord_timeout_member` | 暂停成员，或解除暂停（0 分钟） |
| `discord_kick_member` † | 踢出成员 |
| `discord_ban_member` † | 封禁用户，可选地清除最近的消息 |
| `discord_unban_member` | 解除封禁 |
| `discord_list_bans` | 列出被封禁的用户及其原因 |
| `discord_read_messages` | 读取频道历史记录（分页使用 `before`） |
| `discord_get_message` | 获取单个消息 |
| `discord_send_message` | 发送消息、回复或嵌入 |
| `discord_edit_message` | 编辑机器人发送的消息 |
| `discord_delete_message` † | 删除单个消息 |
| `discord_bulk_delete_messages` † | 删除最多 100 条最近的消息 |
| `discord_pin_message` / `discord_unpin_message` | 管理固定消息 |
| `discord_add_reaction` | 对消息做出反应 |
| `discord_create_invite` | 创建邀请链接 |
| `discord_list_invites` | 列出活动邀请及其使用情况 |
| `discord_list_threads` | 服务器范围的活动线程，以及每个频道的存档线程 |
| `discord_create_thread` | 创建线程或论坛帖子 |
| `discord_edit_thread` | 重命名、存档、锁定、慢速模式 |
| `discord_list_automod_rules` | 列出 AutoMod 规则 |
| `discord_create_automod_rule` | 关键词/正则表达式/垃圾信息/提及垃圾信息/预设规则，带有阻止、提醒和超时操作 |
| `discord_edit_automod_rule` | 编辑规则名称、状态、关键词列表、豁免 |
| `discord_delete_automod_rule` † | 删除 AutoMod 规则 |
| `discord_audit_channel_access` | 有效的查看/发送/管理访问权限，按角色和用户覆盖 |
| `discord_check_member_permissions` | 一个成员的有效权限，服务器范围或按频道 |
| `discord_get_recent_events` | 实时事件日志：加入、离开、封禁、删除、编辑、角色/频道更改 |
| `discord_create_poll` | 发布原生投票（结果可通过 `discord_get_message` 读取） |
| `discord_list_webhooks` | 列出服务器的 Webhook（URL 永远不会暴露） |
| `discord_create_webhook` | 在频道上创建传入 Webhook |
| `discord_send_webhook_message` | 通过 Webhook 发布消息，可选名称/头像覆盖 |
| `discord_delete_webhook` † | 删除 Webhook |
| `discord_list_scheduled_events` | 列出服务器事件及其时间和兴趣计数 |
| `discord_create_scheduled_event` | 创建语音/舞台/外部事件 |
| `discord_edit_scheduled_event` | 编辑详细信息或启动/完成/取消 |
| `discord_delete_scheduled_event` † | 直接删除事件 |
† 除非 `DISCORD_ENABLE_DESTRUCTIVE=true`，否则禁用。
### 事件日志
在服务器运行时，其 Discord 网关连接记录最近 1000 个值得注意的事件存储在内存中（成员加入/离开/更新、封禁、消息删除和编辑、批量删除、频道和角色更改）——如果设置了 `DISCORD_GUILD_IDS`，则过滤到允许的服务器。`discord_get_recent_events` 按服务器、事件类型和时间窗口查询日志。日志在服务器连接到 Discord 时开始记录（启动时），并在重启时重置；它永远不会离开进程。
## 开发
```bash
npm run dev # 从源代码运行并使用 tsx
npm run typecheck # tsc --noEmit
npm run build # 编译到 dist/
```
所有日志记录都输出到 stderr。Discord 连接在启动时在后台启动，以便事件日志从启动时开始记录；如果初始连接失败，则会记录并在下一个工具调用时重试，其中 token 问题会以可读的工具错误显示。每个 MCP 会话都有自己的协议状态，但它们共享一个 Discord 网关连接。空闲 HTTP 会话在 1 小时后被清除；客户端只需重新初始化。
## 许可证
MIT
