适用于 Codex 的 Discord MCP

Discord MCP 是一个本地 Codex 插件，它能将 Discord 机器人以 MCP 工具的形式暴露出来。Codex 在需要时启动桥接服务；无需常驻的网关服务或公共服务器。

[!IMPORTANT] 本项目与 Discord 无关联，也未获得 Discord 的认可或背书。Discord 是 Discord Inc. 的商标。请仅在你被授权管理的服务器中使用此机器人。

要求

• 支持本地插件的 Codex 桌面版

• Node.js 18 或更高版本

• 一个带有机器人用户的 Discord 应用

Related MCP server: Discord MCP Server

它能做什么

• 检查机器人连通状态并生成邀请链接

• 列出可访问的服务器、频道和角色

• 创建、编辑和删除频道

• 发送消息

• 创建、编辑和删除角色

• 添加和移除成员角色

• 通过受护栏保护的读/写回退工具调用任何 guild 作用域的 Discord API v10 JSON 端点

回退层覆盖审核、封禁、超时、AutoMod、帖子、反应、表情回应、贴纸、计划活动、新手引导、音板、权限、机器人管理的 Webhook，以及新增的 guild 作用域 REST 端点，这些都不必等待插件更新即可使用。

Discord 仍会强制执行机器人的权限、已启用的 intents 和角色层级。破坏性工具需要提供特定目标确认令牌。所有常规写入请求都会在执行前提供预览，并要求提供一条与该请求绑定的确认令牌。

设置

1. 在 Discord Developer Portal 中创建一个应用并添加一个机器人。

2. 重置/复制机器人令牌。切勿把它粘贴到聊天中，也不要用保存在这个插件文件夹里。

3. 运行 PowerShell 并执行：

   & "$HOME\plugins\discord-mcp\scripts\configure.ps1"

   脚本会安全地提示你输入令牌，并可选择地输入以逗号分隔的 guild ID 白名单。它会将这些值存储在你的 Windows 用户环境变量中，以便 Codex 将它们转发给 MCP 进程。

4. 配置完成后重启 Codex 桌面应用。

5. 从 Personal marketplace 安装/启用 Discord MCP，然后开始一个新任务。

6. 询问："检查我的 Discord 机器人状态，并给我它的管理员邀请链接。"

7. 打开管理员邀请链接并将机器人授权到预期的服务器。状态结果中还会包含一个最小权限替代方案。

要查找 guild ID，请在 Discord 中启用开发者模式，右键点击服务器图标，然后选择 Copy Server ID。强烈建议设置 DISCORD_ALLOWED_GUILD_IDS；桥接会拒绝该列表之外的任何服务器。

从源码安装

1. 将该仓库克隆到你的本地 Codex 插件目录，名称为 discord-mcp。

2. 将插件添加到本地 Codex marketplace，或使用该仓库的插件清单配合你的现有本地插件工作流。

3. 按下面的说明配置机器人凭据。

4. 安装或启用 Discord MCP，重启 Codex，然后开始一个新任务。

插件清单位于 .codex-plugin/plugin.json，MCP 服务器定义位于 .mcp.json。

发行版下载

每一次通过测试套件的

main push 都会产生一个 GitHub Release，包含：

• 带版本的 discord-mcp-vX.Y.Z-build.N.zip 插件压缩包

• 对应的 SHA-256 校验文件

• 自动生成的发布说明

该压缩包解压后会得到一个 discord-mcp 目录，可以直接放在本地 Codex plugin 目录中。语义化版本来自 package.json；GitHub Actions 运行编号会导致每次主分支构建都有唯一对应关系但不至于重复下载。

配置

• DISCORD_BOT_TOKEN（必填）：Discord 机器人令牌。

• DISCORD_ALLOWED_GUILD_IDS（推荐）：逗号分隔的 Discord guild ID。

运行 scripts/configure.ps1 -Clear 删除这两个用户环境变量。

在 macOS 或 Linux 上，请在启动 Codex 的环境中设置相同的两个变量。例如：

export DISCORD_BOT_TOKEN='your-token'
export DISCORD_ALLOWED_GUILD_IDS='123456789012345678'

不要将真实值写入受版本控制的文件，也不要将它们黏贴到 Codex 任务中。

管理员权限

discord_status 现在会返回：

• administrator_invite_url，它会请求 Discord 的 ADMINISTRATOR 权限位（8）

• least_privilege_invite_url，只会请求插件当前的常用管理权限

• invite_url，为了方便，它指向管理员邀请链接

对于已经加入服务器的机器人，请使用 administrator_invite_url 重新授权，或在 服务器设置 → 角色 中，为其机器人角色启用管理员，然后把机器人放在联系人身下。管理员权限会绕过频道的权限覆盖，但无法绕过角色层级，也不受作用于服务器所有者。

架构

Codex 与一个无运行时依赖的本地 Node.js MCP 服务器通过 stdio 通信。MCP 服务器使用机器人令牌，通过 HTTPS 调用 Discord API v10。它不侦听网络端口、不接收 Discord 消息，也不需要任何有特权的 gateway intents。

覆盖范围与限制

受护栏保护的回退工具支持 guild 作用域的 JSON REST 端点，支持 GET、POST、PUT、PATCH 和 DELETE。请求发起前，它们会先从 guild、channel、stage、invite 或 bot 认证的 webhook 路由中解析 guild 的归属。

这种按需本地桥不实现 Discord Gateway 事件监听、持久化 presence、语音/音频流、需要临时令牌的 interaction 回调、OAuth 用户流程、带 webhook token 的执行路由或多文件上传。这些功能需要独立的连续运行的机器人运行时或专门设计的 upload 流程。带凭证的路由和 JSON 字段会被有意地阻断。

安全说明

• 管理员权限极其强大，请只在你有控制的服务器中使用，保持白名单启用，并像保护密码一样保护机器人令牌。

• 始终保持白名单启用。

• 支持的管理操作会附带 Discord 审计日志的原因字段。

• 原始写入绑定到其方法、路径、查询、请求体以及审计原因；其中任何一项变更都会使确认令牌失效。

• 尝试性的类似敏感字段会在请求体中被阻止；对原始 API 响应也会递归地脱敏。

• 一旦机器人令牌暴露，请立即到 Developer Portal 中重新生成。

有关私密漏洞报告指引，参见 SECURITY.md。

开发

MCP 服务器没有运行时 package 依赖项。可以使用下面的命令运行本地检查和协议 smoke test：

npm test

该冒烟测试使用占位令牌，不会向 Discord 发起请求。Pull request 也会由 GitHub Actions 自动运行。贡献准则见 CONTRIBUTING.md，发布历史详见 CHANGELOG.md。

许可证

源代码基于 MIT License 许可。第三方名称、徽标和商标仍属于各自持有者依归。