Discord MCP

Discord MCP

一个本地 Model Context Protocol 服务，用于读取 Discord 服务器和频道，并且仅在明确允许时发送消息。

• TypeScript + MCP SDK v1
• 本地 stdio 传输
• Discord REST API v10（无需连接 Gateway）
• 服务器/频道允许列表
• 默认只读
• 强制禁止提及通知
• 仅修改/删除由自身机器人撰写的消息

同一个 TypeScript 实现通过 npm、PyPI、OCI 镜像和 Claude Desktop MCPB 发布。PyPI 包也会在 wheel 内运行与发行版一同固定的同一份 JS 代码，而不是用 Python 重新实现服务，或在运行时调用 npx @latest。

TypeScript source
  ├─ esbuild → bundle/discord-mcp.cjs
  │              ├─ npm (npx / pnpm / Yarn / bunx)
  │              ├─ PyPI wheel (uvx / pipx / pip launcher)
  │              ├─ GHCR image (Docker)
  │              └─ MCPB (Claude Desktop one-click bundle)
  └─ server.json → MCP Registry에서 npm / PyPI / OCI 좌표를 한 항목으로 연결

四种发布产物均使用同一个服务包，并根据 esbuild metafile 同时生成包中实际包含的依赖项许可证原文和确定性的 CycloneDX 1.6 SBOM。因此，同一发行版版本不会因包管理器不同而重新解析出不同的传递依赖。

提供的功能

默认公开读取工具。

工具	说明
discord_get_bot	查看机器人账号和当前安全设置
discord_list_guilds	查看机器人加入的服务器列表
discord_get_guild	查看服务器元数据
discord_list_channels	查看服务器的频道列表
discord_get_channel	查看频道元数据
discord_get_messages	查看频道中最多 100 条消息
discord_get_message	查看单条消息

设置 DISCORD_ENABLE_WRITES=true 后会添加以下工具。

工具	说明
discord_send_message	发送普通消息或回复
discord_edit_own_message	仅修改此机器人直接撰写的消息

再设置 DISCORD_ENABLE_DELETES=true 后，会添加 discord_delete_own_message。调用删除操作还需要设置 confirm: true。

同时提供 MCP resource。

• discord://bot
• discord://guilds
• discord://guilds/{guild_id}
• discord://guilds/{guild_id}/channels
• discord://channels/{channel_id}
• discord://channels/{channel_id}/messages/{message_id}

1. 准备 Discord 机器人

1. 在 Discord Developer Portal 中 创建 Application，并在 Bot 菜单中创建机器人。
2. 获取 Bot Token。令牌等同于密码，请勿将其放入代码或 Git 中。
3. 若要读取普通频道的消息正文，请在 Bot 菜单中启用 Message Content Intent。通过 REST 读取消息时也需要此设置。
4. 在 OAuth2 URL Generator 中选择 bot scope，并邀请机器人加入测试服务器。

建议的最低权限：

• 读取：View Channels、Read Message History
• 需要发送消息时：Send Messages
• 需要在 thread 中发送消息时：Send Messages in Threads
• 需要读取 voice channel 的文本时间线时：Connect

无需 Administrator、Manage Messages、Mention Everyone 权限。 频道级 permission overwrite 的优先级高于服务器权限，因此，如果看不到特定频道，请同时检查该频道的权限。

2. 安装

推荐运行时为 Node.js 22 或更高版本。根据分发渠道，可以使用以下命令。为确保 MCP 配置可复现，请固定到确切版本，而不是使用 latest。

渠道	运行命令	所需运行时
npm / npx	npx -y @hypark5540/[email protected]	Node.js 22+
pnpm	pnpm dlx --package=@hypark5540/[email protected] discord-mcp	Node.js 22+
Yarn	yarn dlx -p @hypark5540/[email protected] discord-mcp	Node.js 22+
Bun 包运行器	bunx --package @hypark5540/[email protected] discord-mcp	Bun + Node.js 22+
PyPI / uvx	uvx --from hypark-discord-mcp==0.1.1 discord-mcp	Python 3.9+ + Node.js 22+
PyPI / pipx	pipx run --spec hypark-discord-mcp==0.1.1 discord-mcp	Python 3.9+ + Node.js 22+
Docker / GHCR	下方的 docker run 示例	Docker
Claude Desktop MCPB	GitHub Release 中的 discord-mcp-0.1.1.mcpb	Claude Desktop
MCP Registry	io.github.hypark5540/discord-mcp	取决于客户端选择的包

支持将 bunx 用作 npm 包安装前端。它会直接运行 Node shebang，不支持强制使用 Bun 自身运行时的 bunx --bun 模式。

只有在隔离环境中且不存在已有的 discord-mcp 命令时，才可以按以下方式进行全局安装：

npm install --global @hypark5540/[email protected]
pip install hypark-discord-mcp==0.1.1
hypark-discord-mcp --version

npm 和 Python 渠道都提供独有的 hypark-discord-mcp 命令别名。第三方现有的 npm/PyPI 包也会安装名为 discord-mcp 的全局命令，因此全局安装过程本身可能发生冲突。平时建议使用隔离的 npx/uvx 运行；如果已进行全局安装，请使用独有别名。 Python 包不内置 Node，如有需要，可以通过 DISCORD_MCP_NODE=/path/to/node 指定可执行文件。

在 Docker 中，使用 -i 保持 stdio 连接，不要使用 -t。

docker run --rm -i \
  -e DISCORD_TOKEN \
  -e DISCORD_ENABLE_WRITES=false \
  ghcr.io/hypark5540/discord-mcp:0.1.1

3. 客户端一键连接

Cursor

下方的官方按钮会将确切固定版本的 npm 包注册为 stdio MCP 服务。链接中不包含实际令牌，而是引用 ${env:DISCORD_TOKEN}，因此请先在启动 Cursor 的环境中安全地设置该变量。

如果你正在通过 PyPI 等会移除 cursor:// 链接的页面查看，请前往 GitHub README 的 Cursor 部分点击按钮。

Claude Desktop

下载适用于 Claude Desktop 的 discord-mcp-0.1.1.mcpb后打开文件，即可显示安装界面。Discord Bot Token 不会存储在 MCPB 中，而是通过安装界面的 sensitive 输入项存储在操作系统的 keychain/credential manager 中。可以使用同一版本发布中的 SHA-256 文件验证下载的程序包。如果已安装 GitHub CLI，还可以通过 gh attestation verify --repo hypark5540/discord-mcp discord-mcp-0.1.1.mcpb 验证发布工作流的签名 provenance。

Gemini CLI

Gemini CLI 可以直接安装仓库的官方 Extension 清单。

gemini extensions install https://github.com/hypark5540/discord-mcp --ref=v0.1.1

安装时，Token 设置为 sensitive: true，因此会存储在系统 keychain 中。请勿使用跳过确认界面的选项。

ChatGPT Desktop、Codex 及其他客户端

客户端	推荐连接方式	密钥传递方式
ChatGPT Desktop / Codex CLI·IDE	共享的 ~/.codex/config.toml 本地 stdio 配置	env_vars = ["DISCORD_TOKEN"]
Claude Code / 其他 stdio MCP	固定版本的 npx 配置	客户端密钥存储
ChatGPT 网页版	不支持本地 stdio	需要单独托管的远程 MCP

具体配置请参阅客户端指南；有关 keychain、环境变量和令牌轮换的信息，请参阅密钥管理指南。如果要让 ChatGPT、Claude、Cursor、Gemini 等 Agent 负责安装，可以直接使用AI 安装提示词。

4. 从源代码运行

需要 Node.js 22 或更高版本。

npm run deps:locked
cp .env.example .env
npm run build

deps:locked 会阻止所有依赖项安装脚本，然后仅显式重新构建已锁定并经过审核的 [email protected]。

至少需要在 .env 中设置令牌。

DISCORD_TOKEN=your-bot-token
DISCORD_ENABLE_WRITES=false
DISCORD_ENABLE_DELETES=false
DISCORD_ALLOW_UNRESTRICTED_WRITES=false

如需直接检查，可以运行以下命令。

npm start

stdio 专用于 MCP 帧，因此运行后没有出现普通提示符是正常的。状态日志仅写入 stderr。

5. 连接 MCP 客户端

下面是注册并运行 npm 包的示例。不同客户端的配置文件位置不同，但配置格式 通常如下所示。

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@hypark5540/[email protected]"],
      "env": {
        "DISCORD_TOKEN": "<use-the-client-secret-store>",
        "DISCORD_ENABLE_WRITES": "false",
        "DISCORD_ALLOW_UNRESTRICTED_WRITES": "false",
        "DISCORD_ALLOWED_GUILD_IDS": "123456789012345678",
        "DISCORD_ALLOWED_CHANNEL_IDS": "234567890123456789"
      }
    }
  }
}

如果更喜欢使用 uvx，可以只修改运行部分，如下所示。

{
  "command": "uvx",
  "args": ["--from", "hypark-discord-mcp==0.1.1", "discord-mcp"]
}

直接连接源码构建版本时，与之前一样，将 command 指定为 node，将 args 指定为 ["/absolute/path/to/discord-mcp/dist/index.js"]。

MCP 配置中的 env 优先级高于 .env。由于服务可能从其他目录启动， 建议通过 MCP 客户端的 env 传递令牌。如果客户端支持 native keychain 或环境变量引用， 请优先使用这些功能，不要在上述位置存储令牌原文。

环境变量

变量	默认值	说明
DISCORD_TOKEN	必填	Discord Bot Token
DISCORD_BOT_TOKEN	-	DISCORD_TOKEN 的兼容别名
DISCORD_ENABLE_WRITES	false	注册发送／修改工具
DISCORD_ENABLE_DELETES	false	注册删除工具。writes 也必须为 true
DISCORD_ALLOW_UNRESTRICTED_WRITES	false	有意允许向不在 allowlist 中的所有频道写入
DISCORD_ALLOWED_GUILD_IDS	为空	以逗号分隔的服务器 ID。留空时允许访问机器人可见的所有服务器
DISCORD_ALLOWED_CHANNEL_IDS	为空	以逗号分隔的频道 ID。留空时允许访问获准服务器中的所有 guild channel
DISCORD_MAX_RESPONSE_CHARS	50000	序列化后的 tool/resource 结果最大字符数（1000～200000）
DISCORD_MCP_NODE	PATH 中的 node	PyPI 启动器使用的 Node.js 可执行文件路径

开启 Discord 的 Developer Mode 后，可以通过 Copy ID 获取服务器 ID 和频道 ID。 同时设置两个 allowlist 时，仅允许两者的交集。DM 和群组 DM 始终会被拒绝。在只读模式下， 如果两个 allowlist 均为空，则可以读取机器人能够访问的所有 guild channel。写入模式要求至少 设置一个 allowlist；如需取消此项检查，必须另外明确设置 DISCORD_ALLOW_UNRESTRICTED_WRITES=true。

安全设计

• 仅使用 Bot Token，不支持用户令牌／self-bot。
• 不提供调用任意 Discord API endpoint 的通用工具。
• 必须在启动时通过环境变量单独启用写入和删除工具。
• 所有发送／修改请求都会强制设置 allowed_mentions: { parse: [] }，因此即使包含 @everyone、角色或用户字符串，也不会发送通知。
• 发送操作会应用 Discord nonce 防重。
• 修改／删除前会检查作者 ID，并拒绝 webhook 消息以及其他用户的消息。
• Discord 消息会标记为不可信的外部数据，响应不会在本地保存或缓存。
• 对于引用其他频道的 Discord 回复／线程元数据，会移除正文，以防绕过 allowlist 边界。
• API 错误会转换为不会泄露令牌、请求标头或原始响应 body 的提示。

Discord 的 guild channel 列表 API 可能会返回机器人实际上没有 View Channel 权限的频道名称、 topic 等元数据。对于敏感服务器，请不要只设置 guild allowlist，还应同时设置 channel allowlist。 频道列表包含普通频道和当前 active thread；archived thread 必须通过 ID 直接查询。

虽然可以不设置 allowlist 运行，但在实际使用环境中，建议使用专供机器人使用的测试服务器，并同时设置 DISCORD_ALLOWED_GUILD_IDS、DISCORD_ALLOWED_CHANNEL_IDS。

开发

npm run dev
npm run typecheck
npm test
npm run build
npm run check
npm run build:mcpb
npm run verify:mcpb
npm run build:pypi

测试无需实际调用 Discord，即可验证以下内容：

Vitest 会对可导入的 src 模块按文件强制要求 statements、branches、functions、lines 均达到 100%。 对于轻量的 process bootstrap src/index.ts，不计算覆盖率，而是通过对编译结果和构建产物执行实际的 stdio handshake 进行验证。Codecov 的 project/patch 状态也要求达到 100%，不设容差。

• MCP initialize、tool/resource 列表和调用
• 根据 feature flag 显示写入／删除工具
• Snowflake、分页 cursor、消息长度验证
• 预先拦截 guild/channel allowlist 检查
• 拒绝修改他人消息以及删除确认
• 屏蔽提及并应用 nonce
• 最大响应大小限制
• 编译结果和 PyPI 构建产物的实际 MCP initialize/tools handshake
• Claude MCPB 的官方 CLI pack/unpack/manifest 验证、确定性字节和 stdio handshake
• npm、PyPI、MCP Registry、OCI 元数据的版本一致性

CI 会在 Node.js 22/24 上运行检查，并将生成的 npm tarball 和 Python wheel 分别安装到干净的 环境中，然后再次执行 stdio handshake。还会在 Ubuntu/Windows 的 Python 3.9/3.14 上单独检查 Python wheel 启动器。MCPB 也会独立构建两次，以确认字节一致，并运行通过官方 CLI 重新解压的服务。 有关发布准备和 OIDC Trusted Publishing 设置，请参阅 docs/releasing.md。

隐私与安全报告

此服务不会发送 telemetry，也不会单独存储 Discord 响应。它只会执行本地 MCP 客户端请求所需的 Discord REST 调用。有关数据流和保留范围，请参阅 PRIVACY.md；有关私下报告漏洞的方法，请参阅 SECURITY.md。请勿在公开 issue 或日志中 包含 Bot Token。

문제 해결

• 401 / 토큰 거부: Bot 메뉴에서 토큰을 재발급하고 DISCORD_TOKEN을 갱신하세요. Bot 접두사는 직접 붙이지 않습니다.
• 403 / 권한 없음: 채널의 View Channel, Read Message History, 필요 시 Send Messages를 확인하세요.
• 메시지 내용이 비어 있음: Developer Portal에서 Message Content Intent를 활성화했는지 확인하세요.
• 쓰기 도구가 목록에 없음: MCP 클라이언트 프로세스의 DISCORD_ENABLE_WRITES가 문자열 true인지 확인하고 클라이언트를 재시작하세요.
• allowlist 오류: ID는 이름이나 URL이 아니라 17~20자리 숫자 문자열이어야 합니다.

Discord의 공식 권한·intent·rate limit 세부사항은 OAuth2 and Permissions, Gateway Intents, Message Resource, Rate Limits을 참고하세요.