discord-management-mcp

Discord 管理 MCP

从任意 MCP 客户端安全地管理 Discord

Discord Management MCP 是一个本地 Model Context Protocol（MCP）服务，用于检查、备份和管理 Discord 服务器。它通过 stdio 运行，将机器人令牌和备份文件保存在操作者的计算机上，并在每项变更操作前设置确认、备份和恢复防护。该服务提供 54 个工具，涵盖服务器清单、审核、角色、频道、服务器设置、备份和恢复规划。

它适用于任何支持本地 stdio 服务的 MCP 客户端，包括 Claude Desktop、Claude Code、Cursor、VS Code、Codex、Windsurf 和 Cline。本项目由独立开发，与 Discord Inc. 无关联，也未获其认可、赞助或批准。

不熟悉 Discord 机器人？设置与首次使用指南将引导你创建应用、使用正确的权限邀请机器人、复制服务器 ID、注册客户端、验证连接，并执行首次安全备份和恢复。

安装

发布的包只需一条命令即可运行：

npx --yes discord-management-mcp

该包以 discord-management-mcp 的名称发布在 npm 上，并通过 package.json 和 server.json 声明 io.github.TheStreamCode/discord-management-mcp 的 MCP 注册表元数据。

在客户端中注册

每个客户端都需要相同的命令、参数和 DISCORD_TOKEN 环境变量。将以下条目等效的配置粘贴到客户端的 MCP 配置中：

{
  "mcpServers": {
    "discord-management": {
      "command": "npx",
      "args": ["--yes", "discord-management-mcp"],
      "env": {
        "DISCORD_TOKEN": "your_bot_token"
      }
    }
  }
}

客户端	注册方式
Claude Desktop	将上述条目添加到 MCP 服务配置中。
Claude Code	添加具有相同命令和参数的本地 stdio 服务。
Cursor	将上述条目添加到 MCP 配置中。
VS Code	在客户端的 MCP 配置中添加相同的命令和参数。
Codex	添加具有相同命令和参数的 stdio 服务条目。
Windsurf	将上述条目添加到 MCP 配置中。
Cline	在 MCP 设置面板中添加该服务。

Claude Desktop、Cursor、Windsurf 和 Cline 支持上方所示的 mcpServers JSON 结构。使用其他配置架构的客户端也支持相同的 command、args 和 env 值。具体文件或命令请参阅各客户端自己的文档。

设置

简要步骤如下，完整流程请参阅设置与首次使用：

1. 创建机器人。 Developer Portal > New Application > Bot > Reset Token。该令牌是服务唯一需要的凭据。不要使用 Application ID、Public Key 或 OAuth2 client secret。
2. 邀请机器人。 OAuth2 > URL Generator > 选择 bot 范围，并添加所需权限。建议从 View Channels、Manage Channels、Manage Roles、Manage Server、View Audit Log，以及计划使用的审核权限开始。然后将机器人角色拖到它需要编辑的角色上方。
3. 复制服务器 ID。 启用 Developer Mode，右键点击服务器图标，然后选择 Copy Server ID。这个数字是 guildId 参数，不是机器人的应用 ID。
4. 注册客户端。 使用向客户端注册中的配置，并在 env 中设置 DISCORD_TOKEN；或者将令牌放入工作目录下的 .env.local。
5. 验证并备份。 让客户端运行 discord_list_guilds，然后针对你的服务器运行 discord_backup_create，并查看 coverage.channels.complete。

首次请求示例：

Use discord_list_guilds, then discord_backup_create for the server I name, and report the backup ID and coverage.

之后只通过受保护的流程进行更改：创建备份、检查目标对象、应用一项小改动，并确认结果。每次变更都需要提供审核原因：

{
  "guildId": "123456789012345678",
  "confirm": true,
  "reason": "Create the approved community announcements channel"
}

高影响操作还需要提供与服务器匹配的 backupId，除非操作员明确接受 allowWithoutBackup: true。工具目录列出了每个变更工具的具体策略。

为什么选择它

许多 Discord MCP 服务仅支持只读检查或预览更改，有些还会通过托管服务传递机器人令牌。Discord Management MCP 可在本地执行更改，但仅通过保护与恢复流程进行：

能力	典型的仅预览服务	Discord Management MCP
只读检查	是	是，提供 23 个只读工具
执行更改	否	是，提供 31 个变更与审核工具
风险更改前进行本地备份	很少	JSON schema v2 快照，包含频道覆盖情况
恢复	否	先生成带计划哈希的计划，再应用并进行预恢复备份
回滚保证	不提供	尽力恢复，并如实报告 NOT_RESTORED 警告
数据路径	通常为托管服务	仅限本地 stdio

实际意义如下：

• 专为本地运行而设计。 机器人令牌、快照、恢复计划和 stdio 传输都保留在操作员的计算机上。没有托管中继，也没有公共 HTTP 监听器。
• 先预览，再应用。 在进行任何更改之前，可以比较备份差异并生成恢复计划；计划会携带一个哈希值，供应用时验证。
• 以备份为恢复保障。 高风险更改可指定同一服务器的快照；恢复应用会在首次更改 Discord 之前写入新的预恢复备份。
• 明确的安全策略矩阵。 每次 Discord 变更都需要 confirm: true 和原因。列出的高影响工具需要同一服务器的备份。紧急事件处置操作无需备份也可使用。
• 如实报告恢复情况。 恢复会报告已跳过、有损、已应用和失败的操作，而不会承诺不可能实现的完整回滚。

备份与恢复

恢复流程分为三个步骤：

1. discord_backup_create 会以原子方式将 JSON 快照写入 BACKUP_DIR，剔除邀请代码、Webhook 令牌和其他机密，并在 coverage.channels 中记录频道覆盖范围。
2. discord_backup_diff 和 discord_backup_restore_plan 会显示将发生哪些更改。计划包含 planHash，以及针对已捕获但 Discord 无法重建的部分发出的 NOT_RESTORED 警告。
3. discord_backup_restore_apply 可以验证 expectedPlanHash，先创建恢复前备份，然后保守地应用受支持的角色和频道字段。删除操作仍需显式启用。

删除并重新创建后，Discord 无法恢复原始 ID、消息或审计日志历史记录、完全相同的邀请代码、Webhook 令牌，以及所有社区和发现设置。服务会如实报告这些限制，而不是将其隐藏。完整说明请参阅安全与备份。

工具覆盖范围

服务会注册 54 个工具。所有工具名称请参阅工具目录，备份策略请参阅防护矩阵。

领域	工具数
服务器、成员和审计清单	17
备份与恢复	6
频道	6
角色	7
管理与 AutoMod	13
服务器配置	5
总计	54

只读工具会标注为只读，且从不需要确认。会修改 Discord 的工具需要 confirm: true 和非空审计原因；所有修改操作都会通过共享队列运行，以避免交错执行。discord_backup_create 只会写入本地快照，无需确认。

安全模型

• 每项 Discord 修改操作都需要 confirm: true 和非空的 reason；在 Discord 支持审计日志原因的地方，此原因会传递给 Discord。
• 高影响工具需要提供来自同一服务器的备份，或明确确认 allowWithoutBackup: true。
• discord_set_incident_actions 有意豁免此要求：它用于应对突袭，其更改可撤销。
• 恢复应用会自行创建恢复前备份，并在每种错误情况下保留其 ID。
• 备份写入采用原子操作；备份路径限定在项目目录内，并拒绝符号链接和 junction。
• 只读工具均以只读方式实现并标注。

防护矩阵、频道覆盖范围和恢复行为请参阅安全与备份；运行时模型请参阅设计与信任边界。请通过 SECURITY.md 私下报告漏洞。

要求

• Node.js 24 或更高版本。
• 一个带有 Bot 令牌的 Discord 应用。
• 邀请到目标服务器的 Bot，且仅授予预期工具所需的权限。

ENABLE_MESSAGE_CONTENT 和 ENABLE_GUILD_MEMBERS 均为可选启用项，且需要在 Discord Developer Portal 中启用相应的特权意图。自 2026-06-10 起，Discord 会在用户数达到 10,000（而非 100 个服务器）时审核特权意图的使用情况，获批应用必须每年重新申请。详情请参阅配置。

配置

首先从进程环境中读取配置，然后从工作目录中的 .env.local 读取。布尔值接受 true/false、yes/no、on/off 或 1/0。

变量	用途	默认值
DISCORD_TOKEN	来自 Developer Portal > Bot > Token 的 Discord Bot 令牌	必需
BACKUP_DIR	本地 JSON 备份的相对目录；必须位于项目目录内	backups
LOG_LEVEL	标准错误日志级别：error、warn、info 或 debug；日志为 JSON 行格式	info
ENABLE_MESSAGE_CONTENT	启用消息内容工具，并要求启用 Discord Message Content 意图	false
ENABLE_GUILD_MEMBERS	为需要此意图的工作流启用 Guild Members 网关意图	false

令牌规则、日志行为和特权意图设置请参阅配置参考。

隐私与安全

所有内容都通过 stdio 在本地运行：机器人令牌、备份文件、恢复计划以及服务进程本身都不会离开操作者的计算机。所有变更都需要明确确认；在制定计划或恢复之前，备份还会经过大小、深度、结构、符号链接和服务器身份验证。恢复操作会在首次修改 Discord 之前创建恢复前备份，并在操作失败时如实停止。有关完整模型，请参阅设计与信任边界和安全性与备份；有关私下报告漏洞的信息，请参阅 SECURITY.md。

故障排除

服务器因缺少或无效的 DISCORD_TOKEN 而退出

在进程环境中或工作目录下的 .env.local 中设置 Bot Token。如果某个值看起来像 Discord Application Public Key，系统会明确拒绝：请使用 Bot Token，而不是 Application ID、Public Key 或 OAuth2 客户端密钥。

返回的消息内容为空

消息内容工具需要同时设置 ENABLE_MESSAGE_CONTENT=true，并在 Discord Developer Portal 中启用 Message Content Intent。如果缺少其中任何一项，Discord 可能会返回空的 content、embeds 和 attachments 字段。更改任一设置后，都要重启服务器。如果应用即将达到审核门槛，请记住，特权 Intent 访问权限会在用户数达到 10,000 时接受审核，并且必须每年续期。

变更在到达 Discord 之前被拒绝

变更工具需要 confirm: true 和非空的 reason。高影响工具还需要提供来自同一服务器的 backupId，或明确确认 allowWithoutBackup: true。紧急情况下使用的 discord_set_incident_actions 是例外。重试前请查看防护矩阵。

备份或频道列表中缺少频道

机器人只能备份其有权查看的频道。从 2026-11-16 开始，Discord 会从 GET /guilds/{id}/channels 中省略机器人无权查看的频道，网关负载中也可能包含经过混淆处理的频道对象。备份会在 coverage.channels 中记录这一情况，并在覆盖不完整时发出警告。对于重要频道，请授予 VIEW_CHANNEL 权限；并将 complete: false 视为部分回滚点。请参阅频道覆盖范围与混淆处理。

恢复报告显示已跳过或有损操作

Discord 无法重建原始 ID、消息或审计日志历史记录、完全相同的邀请码、Webhook 令牌、托管的集成对象，也无法重建所有社区和发现设置。请检查计划的 planHash 和其中的 NOT_RESTORED 警告，然后在重试前查看报告中的操作。

日志过于简略或过于冗长

将 LOG_LEVEL 设置为 error、warn、info 或 debug。日志以 JSON 行的形式写入 stderr，因此 stdout 保留给 MCP 协议流量。诊断工具调用时使用 debug，需要安静运行时使用 error。

开发

要求：Node.js 24 或更高版本，以及与 lockfile 匹配的 npm。

git clone https://github.com/TheStreamCode/discord-management-mcp.git
cd discord-management-mcp
npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run verify:mcp
npm run preflight
npm run pack:check
npm audit --omit=dev --audit-level=high

npm run verify:mcp 会使用占位令牌通过 stdio 启动构建后的服务器，并检查其声明的 MCP 接口：54 个工具、确定性的工具列表、标题、描述、输入和输出架构，以及注释提示。它不会调用 Discord API。

测试使用模拟对象，不得联系 Discord。常规验证绝不会执行实时变更。仓库将工程指导保存在 AGENTS.md 中；该文件不会随 npm 包发布。贡献规则请参阅 CONTRIBUTING.md。

支持

请参阅 SUPPORT.md。可通过 GitHub Issues 提交可复现的错误和功能提案，并通过 GitHub Security Advisories 私下报告漏洞。

贡献

请参阅 CONTRIBUTING.md。拉取请求必须通过 npm run preflight、npm run verify:mcp 和必需的 CI 检查。

许可证

MIT，详见 LICENSE。版权所有 (c) 2026 Michael Gasperini (Mikesoft)。

本项目为独立开发，与 Discord Inc. 无关，也未获得其认可、赞助或批准。Discord 是 Discord Inc. 的商标。适用的 Discord 条款和政策请参阅 NOTICE。

---

由 Michael Gasperini (Mikesoft) 维护。 如果本项目能帮助你安全地管理 Discord 社区，不妨考虑 赞助其维护工作。