用途
discord-mcp 是一个 MCP（Model Context Protocol）服务器，用于通过自然语言控制 Discord。它可接入 Claude Desktop、Claude Code、Cursor、VS Code Copilot 或任何兼容 MCP 的客户端，让用户以对话方式管理整个 Discord 服务器，包括消息、频道、角色、权限、成员与审核等操作。
主要能力
- 提供 95+ 工具，覆盖消息、频道、角色、权限、审核、论坛、Webhook、定时事件、邀请、私信、嵌入内容等。
- 支持多服务器（multi-guild），不锁定单一 GUILD_ID。
- 轻量：TypeScript + Node.js，包体约 70kB，Docker 镜像约 73MB（对比 Java 方案 400MB+）。
- 模块化：清晰架构，便于扩展新工具。
- 两种安装方式：npm 或 Docker。
使用方式
在 MCP 客户端配置中加入服务器配置，并将 YOUR_TOKEN_HERE 替换为机器人令牌。使用 npx 无需安装。
- Claude Desktop：将配置加入 claude_desktop_config.json。macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json；Windows 路径为 %APPDATA%\Claude\claude_desktop_config.json。保存后重启 Claude Desktop。
- Cursor：将配置加入 ~/.cursor/mcp.json。
- VS Code：加入 .vscode/mcp.json。
也可在项目根目录创建 .env 文件，服务器通过 dotenv 自动加载。
环境变量
- 自 2.1.1 起，服务器不再请求 GuildMessages intent：不订阅消息事件，所有返回的消息均通过 REST 获取，连接 intent 不限制此操作。DISCORD_MESSAGE_CONTENT 仅影响连接时是否请求 Message Content intent，不改变任何工具返回内容。
- 这些标志仅控制服务器在识别时请求哪些网关 intent。请求未在 Developer Portal 启用的特权 intent 会导致首次工具调用时连接失败（关闭码 4014）；将标志设为 false 可继续连接。
- 数据访问由门户开关控制，而非这些标志：服务器通过 REST API 读取一切，Discord 仅依据门户设置进行限制。门户开关开启时，将标志设为 false 不会丢失任何内容。门户开关关闭时，对应数据受限：消息正文返回为空（content、embeds、attachments；机器人自己的消息、私信及提及机器人的消息除外），成员列表失败；在门户中启用开关可恢复。
- 工具集（DISCORD_MCP_TOOLSETS）：discovery、messages、channels、permissions、members、roles、moderation、screening、stats、forums、webhooks、scheduled_events、invites、dm。例如 DISCORD_MCP_TOOLSETS=discovery,messages,members 仅暴露 discovery、message 和 member 工具。注意：工具集包含其整个模块，包括破坏性工具（messages 含批量删除；members 含踢出/封禁）；使用 DISCORD_ALLOWED_GUILDS 和 dry-run 默认值加以约束。仅列出的工具集会被公布并可调用。未知名称会导致服务器启动失败，而非静默暴露全部（空值视为未设置，暴露全部）。
创建 Discord 机器人
- 访问 discord.com/developers/applications
- New Application > 命名
- Bot 标签 > Reset Token > 复制令牌
- 启用 Privileged Gateway Intents（服务器默认请求两者，但新 Discord 应用的门户开关为 OFF）：Server Members Intent、Message Content Intent。重要：若机器人请求未在此启用的特权 intent，Discord 会以代码 4014 关闭连接，所有工具调用失败。启用两者，或通过上述环境变量停止请求不需要的 intent。
- OAuth2 > URL Generator：Scopes 选 bot；Permissions 选 Send Messages、Read Message History、Manage Channels、Manage Roles、Kick Members、Ban Members、Moderate Members、View Audit Log、Manage Messages、Manage Threads、Add Reactions、Manage Guild、Manage Webhooks、Manage Events、Create Events、Create Instant Invite、Manage Nicknames、Pin Messages、Embed Links、Create Public Threads、Send Messages in Threads。
- 复制生成的 URL 并邀请机器人加入服务器。
可用工具（99）
- Discovery & Navigation（4 个工具）
- Messages（20 个工具）
- Channels（8 个工具）
- Channel Permissions（6 个工具）
- Members（11 个工具）
- Roles（9 个工具）
- Forums（10 个工具）
- Webhooks（8 个工具）
- Scheduled Events（7 个工具）
- Direct Messages（7 个工具）
- Invites（5 个工具）
- Moderation & Screening（3 个工具）
查找 Discord ID
在 Discord 中启用开发者模式：Settings > Advanced > Developer Mode。然后右键点击服务器、频道或用户 > Copy ID。
项目结构与扩展
添加新工具：
- 在 src/tools/ 创建新文件（如 events.ts）。
- 使用 defineTool({ name, description, annotations, schema, handle }) 声明每个工具，并导出 defineModule([...]) 作为默认导出。
- 在 src/tools/index.ts 中导入并加入 allToolsets（键为其 DISCORD_MCP_TOOLSETS 名称）。
安全建议
- 切勿将 Discord 令牌提交到 Git。
- 使用环境变量或 .env 文件（不纳入版本控制）。
- 仅授予机器人所需权限。
- 使用 DISCORD_ALLOWED_GUILDS 将服务器限制到特定服务器。
- 不可逆的大规模操作（bulk_ban、prune_members、bulk_delete_messages、delete_channel）默认使用 dry_run 预览；传入 dry_run:false 才会执行。
贡献
欢迎贡献：Fork 仓库、创建功能分支（git checkout -b feature/my-feature）、遵循模块化结构（见 Adding a new tool）、提交更改并打开 pull request。
许可
MIT，详见 LICENSE。
