omnicord

Omnicord

面向 AI Agent 的 Discord 服务器管理 MCP 服务。

Omnicord 是一个 MCP 服务，让你的 AI 助手能够全面操作 Discord 服务器。从日常聊天、内容管理到服务器管理，甚至可以根据一段简短的需求描述，搭建起完整的社区服务器。

你描述想要什么，由 AI 决定如何实现。Omnicord 确保一切正确完成，并且未经你同意，绝不执行破坏性操作。

工作原理

你的 AI 客户端（Claude Desktop、Cursor、Windsurf、Claude Code 或其他 MCP 客户端）负责思考。Omnicord 负责执行：它通过你自己的机器人与 Discord 通信，在 Discord 的规则造成影响前加以遵守，在速率限制下有序排队，并要求你先预览并确认所有破坏性操作。Omnicord 内部没有大模型，背后也没有云服务。你的机器人令牌保存在你本机的文件中。

快速开始

你需要 Node 20 或更高版本，以及一个 Discord 账号。只需一条命令：

npx @orygn/omnicord init

或从源代码开始：

git clone https://github.com/OrygnsCode/Omnicord.git && cd Omnicord
npm install
npm run build
node dist/index.js init

想看演示？这里有完整的设置流程：

这个演示现在有些过时了，但核心步骤仍然适用。我们计划推出更完整、更新后的演示。

向导会在大约一分钟内将一个空白的 Discord 应用配置为可正常工作的设置。它会在隐藏输入内容的情况下接收机器人令牌，通过 Discord 实时验证令牌，检查特权意图开关，并在发现有开关关闭时等待你修复；根据你选择的权限级别生成邀请链接；在本地保存令牌（源代码检出时保存到被 git 忽略的 .env，通过 npx 或全局安装时保存到用户文件夹中的 .omnicord/.env）；并将 omnicord 配置写入你的 AI 客户端配置文件（先备份该文件）。它会自动检测 Claude Desktop（包括 Microsoft Store 版本）、Cursor、Windsurf 和项目级 Claude Code，即使你还没有在其中设置 MCP 也能检测到；其他客户端则会提供可供粘贴的配置片段。它只会添加 omnicord 配置项，绝不会覆盖文件的其他内容。

接下来，完全重启你的 AI 客户端，并向它询问：

检查一下我的 Discord 机器人设置

共有八项检查，结果以通俗易懂的语言呈现，并为所有问题提供准确的修复方法。

之后要更新时，运行 npx @orygn/omnicord@latest init，然后选择重新向 AI 客户端注册。你的机器人和设置都会保留。

功能

领域	示例
构建服务器	根据简要说明规划并执行完整的服务器构建：在一次增量操作中设置角色、类别、频道和权限。将布局保存为蓝图，并进行差异比较和重建。
消息	发送、编辑、置顶、转发、添加回应、创建投票、定时发送消息、发送私信、使用 Webhook，以及为规则和欢迎面板创建丰富的 Components V2 布局。
读取	频道历史记录、全文消息搜索、成员、角色、权限、审计日志。
管理	超时、踢出、封禁、批量操作和清理操作，执行前均会预览；还可启用突袭锁定，暂停邀请和私信。
自动管理	Discord 服务端筛选器：关键词规则、Discord 维护的预设列表（侮辱性词语、脏话）、成员资料检查、垃圾消息和提及刷屏限制。
实时	订阅服务器实时事件，并询问“我错过了什么？”
结构	频道、类别、权限覆盖、重新排序、克隆、语音频道状态。
社区	活动（单次或定期）、舞台、话题串、论坛、邀请、欢迎页面、新成员引导。
表达	表情符号、贴纸、音效板音效。
诊断	设置检查、机器人信息、速率限制状态、权限说明。

每个工具的完整规范请参阅 工具目录。

安全模型

破坏性操作（删除、封禁、踢出、超时、批量操作）首次调用时绝不会执行。它们会返回易于理解的预览，以及绑定到该确切操作的确认令牌；使用令牌重复调用即可执行操作。令牌只能使用一次，并会在两分钟后过期。管理操作还会在确认门槛前预先检查 Discord 的层级规则、所有者保护和自我保护，因此失败时会提供说明，而不是返回 403。

此机制由 Omnicord 本身强制执行，而非依赖模型判断。即使 AI 会话发生混乱或遭到入侵，也无法绕过确认门槛。

多个机器人

Omnicord 可通过一次安装驱动多个机器人，每个服务器使用一个。将其指向某个服务器后，它会使用实际加入该服务器的机器人，因此测试机器人和真实机器人，或每个社区各自的机器人，都能并行运行，无需切换令牌。设置时回答向导中的“多少个机器人”提示，或手动在 bots.json 中配置。破坏性操作的预览会标明执行操作的机器人，以便在操作运行前发现路由错误。单个 DISCORD_TOKEN 保持不变，不会涉及这些操作。详情请参阅 多个机器人。

运行

Stdio（默认方式），适用于桌面 MCP 客户端：

node dist/index.js

Streamable HTTP，适用于支持远程连接的客户端和自托管：

node dist/index.js --http              # 127.0.0.1:3414/mcp
node dist/index.js --http --port 8080

机器人令牌位于 HTTP 端点之后，因此默认安全限制很严格：未设置 OMNICORD_HTTP_TOKEN 时，若绑定地址超出 localhost，服务将拒绝启动；Bearer 身份验证采用恒定时间比较；除非列入允许列表，否则会拒绝浏览器来源；在环回模式下会验证 Host 标头，以防止 DNS 重绑定。详情请参阅自托管。

Docker

已发布的镜像托管在 Docker Hub（orygn/omnicord），也可以自行构建。该镜像以非 root 用户运行 HTTP 传输，并将容器健康检查连接到健康检查端点。镜像会绑定到环回地址之外，因此必须设置 OMNICORD_HTTP_TOKEN；未设置时，程序会退出并显示清晰的提示信息。令牌不会存放在镜像中；所有内容均在运行时通过环境变量提供。

docker run -d -p 3414:3414 \
  -e DISCORD_TOKEN=your-bot-token \
  -e OMNICORD_HTTP_TOKEN=a-strong-secret \
  orygn/omnicord

也可以自行构建：docker build -t omnicord .。或者使用 compose，在导出两个机密信息后运行：docker compose up -d。

配置

环境变量或 .env 文件（向导会为你写入；源码检出时，文件位于 package.json 旁边；通过 npx 和全局安装时，文件位于用户文件夹中的 .omnicord/.env）。多个机器人在同一目录下的 bots.json 中配置；请参阅多个机器人。

变量	用途
DISCORD_TOKEN	机器人令牌。实际使用时必需；未设置时，服务仍会启动，诊断信息会说明需要修复什么。
OMNICORD_GUILD	可选的默认服务器 ID，这样工具就可以省略 guild 参数。
OMNICORD_TOOLS	要加载的工具组。未设置时会加载全部 155 个工具。请参阅工具集。
OMNICORD_SAFE_MODE	默认开启。破坏性工具会先预览，并要求确认令牌；仅在可信自动化场景中将其设为 false。
OMNICORD_GATEWAY	设置令牌后默认开启：机器人会显示为在线，实时事件订阅也会生效。设为 off 则仅使用 REST。
OMNICORD_HOME	可选。用于存放 .env、bots.json 和保存的数据的目录。源码检出时默认为软件包根目录；安装后默认为用户文件夹中的 .omnicord。
OMNICORD_DATA_DIR	保存的蓝图和计划消息的存放位置。默认值：源码检出时为 package.json 旁边的 .omnicord；安装后为用户文件夹中的 .omnicord。
OMNICORD_PORT	HTTP 端口，默认为 3414。
OMNICORD_HTTP_HOST	HTTP 绑定地址，默认为 127.0.0.1。
OMNICORD_HTTP_TOKEN	HTTP 模式的 Bearer 令牌。绑定到 localhost 以外的地址时必需。
OMNICORD_HTTP_ORIGINS	允许调用 HTTP 端点的浏览器来源，使用逗号分隔。留空表示不允许任何来源。

stdio 客户端配置（Claude Desktop 及兼容客户端）：

{
  "mcpServers": {
    "omnicord": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"]
    }
  }
}

客户端配置中不需要放入令牌。无论客户端从哪个位置启动，服务都能找到 .env 和 bots.json：它会依次检查已设置的 OMNICORD_HOME、当前目录、软件包根目录，然后是用户文件夹中的 .omnicord；实际环境变量的优先级高于以上所有位置。

文档

文档	内容
快速入门	几分钟内完成设置，可使用向导或手动操作。
多个机器人	从一次安装中运行多个机器人，每个机器人对应一个服务器。
连接 AI 客户端	Claude Desktop、Claude Code、Cursor、Windsurf、ChatGPT 及其他客户端的准确配置。
自托管	HTTP 传输、Docker，以及网络部署的安全模型。
故障排除	常见问题及其解决方法。
安全白皮书	通俗说明 Omnicord 能做什么、不能做什么，供决定是否安装的人参考。
SECURITY.md	工程层面的威胁模型和审计结果。
工具目录	全部 155 个工具的完整契约。

这些文档也适合 AI 助手阅读：把页面粘贴给你的 AI，让它引导你完成操作。

Omnicord 也已列入官方 MCP 注册表、Smithery 和 Docker Hub。

测试

node scripts/unit.mjs        # pure logic: resolver, permissions, planner, gate
node scripts/smoke.mjs       # stdio protocol session, no token needed
node scripts/smoke-http.mjs  # HTTP transport, sessions, auth, security gates
node scripts/acceptance.mjs  # live end-to-end against a real test server

验收测试套件需要将 DISCORD_TOKEN 和 OMNICORD_GUILD 指向一个可随意使用的测试服务器，并会在测试后清理数据。scripts/smoke-docker.mjs 会构建并验证容器镜像，需要 Docker 守护进程正在运行。

单元测试套件和冒烟测试套件都不需要 Discord 令牌，因此你可以先观察确认关卡如何拦截破坏性调用，再仅凭令牌放行，然后再放心地将此服务用于自己的机器人。

贡献

欢迎提交 Bug 报告和拉取请求。 CONTRIBUTING.md 介绍了项目布局、测试套件、约定，以及一条硬性规则：任何会删除内容、移除访问权限、惩罚成员或将更改传播到多个实体的工具，都必须经过确认关卡。项目遵循 Contributor Covenant。

许可证

Omnicord 基于 Elastic License 2.0 提供源代码。简单来说：任何人都可以自由阅读、使用、修改和自托管，包括运行自己社区的企业。该许可证唯一禁止的行为，是将 Omnicord 作为托管或管理服务提供给第三方。代码公开是为了接受审计；但不得将其作为服务转售。

版本管理

采用语义化版本管理，并记录在 CHANGELOG.md 中。1.0.0 标志着公开发布；此后的版本均遵循 semver，上方的 npm 徽章显示当前版本。package.json 中的版本会自动同步到各处：MCP 服务标识、健康检查端点和向导。

由 Orygn LLC 构建。安全问题报告请发送至： [email protected]。