discord-mcp

为什么选择这个？

• 95+ 个工具：消息、频道、角色、权限、审核、论坛、Webhook、定时活动、邀请、私信、嵌入消息等
• 支持多个服务器：可在多个服务器中使用，不受 GUILD_ID 限制
• 轻量级：TypeScript + Node.js，软件包约 70kB，Docker 镜像约 73MB（而 Java 替代方案超过 400MB）
• 模块化：架构清晰，易于扩展新工具
• 两种安装方式：npm 或 Docker，任你选择

快速开始

将以下内容添加到 MCP 客户端配置中，并将 YOUR_TOKEN_HERE 替换为你的机器人令牌：

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@pasympa/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

无需安装，npx 会处理所有事情。

还没有机器人？请参阅创建 Discord 机器人。

配置

claude mcp add discord -e DISCORD_TOKEN=YOUR_TOKEN_HERE -- npx -y @pasympa/discord-mcp

{
  "inputs": [
    {
      "type": "promptString",
      "id": "discord-token",
      "description": "Discord Bot Token",
      "password": true
    }
  ],
  "servers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@pasympa/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "${input:discord-token}"
      }
    }
  }
}

{
  "mcpServers": {
    "discord": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DISCORD_TOKEN=YOUR_TOKEN_HERE",
        "pasympa/discord-mcp:latest"
      ]
    }
  }
}

git clone https://github.com/PaSympa/discord-mcp
cd discord-mcp
npm install && npm run build

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp/dist/index.js"],
      "env": {
        "DISCORD_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

DISCORD_TOKEN=YOUR_TOKEN_HERE

从 2.1.1 开始，服务不再请求 GuildMessages 意图：此处没有任何功能会订阅消息事件，而且服务返回的每条消息都是通过 REST 获取的，不受连接意图限制。此前，该意图会让 discord.js 缓存所有频道中流经的每条消息及其作者信息，导致长时间运行的服务中缓存无限增长。现在，缓存清理器会限制缓存规模。因此，DISCORD_MESSAGE_CONTENT 只影响连接时是否请求 Message Content 意图，不会改变任何工具返回的内容。

这些标志只控制服务在识别身份时请求哪些网关意图。请求 Developer Portal 中未启用的特权意图，会导致连接在首次工具调用时失败（关闭代码 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 只会开放发现、消息和成员工具。注意：工具集包含其整个模块，包括具有破坏性的工具（messages 包含批量删除；members 包含踢出／封禁）；请使用 DISCORD_ALLOWED_GUILDS 和默认的试运行设置来限制其影响范围。只有列出的工具集中的工具才会被公布并可供调用。若包含未知名称，服务会在启动时失败，而不会静默开放所有工具（空值视为未设置，会开放所有工具）。

创建 Discord 机器人

1. 前往 discord.com/developers/applications

2. 点击 New Application > 为应用命名

3. Bot 选项卡 > Reset Token > 复制令牌

4. 启用 Privileged Gateway Intents（此服务默认会请求这两项，但新建的 Discord 应用在开发者门户中默认关闭这些开关）：

   • Server Members Intent
   • Message Content Intent

   **重要：**如果机器人请求了此处未启用的特权意图，Discord 会以代码 4014 关闭连接，导致每次工具调用都失败。请启用两项，或者通过上方的环境变量停止请求不需要的意图。

5. 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

6. 复制生成的 URL，并邀请机器人加入你的服务器

可用工具（99）

发现与导航（4 个工具）

消息（20 个工具）

频道（8 个工具）

频道权限（6 个工具）

成员（11 个工具）

角色（9 个工具）

论坛（10 个工具）

Webhook（8 个工具）

预定活动（7 个工具）

私信（7 个工具）

邀请（5 个工具）

审核与筛选（3 个工具）

统计（1 个工具）

使用示例

"List all servers the bot is in"
"Read the last 10 messages in #general"
"Send 'Hello everyone!' to the announcements channel"
"Create a forum channel called 'feedback' with tags Bug, Feature, Question"
"Show the full permission audit for the server"
"Create a webhook on #notifications and send a test message"
"Ban user 112233445566778899 and delete their messages from the last 3 days"
"Create an event called 'Game Night' for next Friday at 8pm"
"List all upcoming events in the server"
"Create a permanent invite for #general"
"List all active invites and delete expired ones"
"Send a DM to user 112233445566778899 saying 'Your build passed!'"
"Search for members named 'john'"
"List all banned users in the server"
"Show all pinned messages in #general"
"Forward that message to #announcements"

查找 Discord ID

在 Discord 中启用开发者模式： Settings > Advanced > Developer Mode

然后在服务器、频道或用户上右键单击 > 复制 ID。

项目结构

discord-mcp/
├── src/
│   ├── index.ts             ← Entry point (MCP server + transport)
│   ├── client.ts            ← Discord client + shared helpers
│   ├── constants.ts         ← Shared constants (limits, defaults)
│   ├── embeds.ts            ← Shared embed schema + builder
│   └── tools/
│       ├── index.ts         ← Tool registry (toolset gating, dispatch)
│       ├── define.ts        ← defineTool/defineModule + shared zod fields
│       ├── types.ts         ← Shared TypeScript interfaces
│       ├── discovery.ts     ← Guild/channel discovery
│       ├── messages.ts      ← Message CRUD, reactions, threads, embeds
│       ├── channels.ts      ← Channel management
│       ├── permissions.ts   ← Permission overwrites
│       ├── members.ts       ← Member management
│       ├── roles.ts         ← Role CRUD and assignment
│       ├── moderation.ts    ← Audit log
│       ├── screening.ts     ← Membership screening
│       ├── stats.ts         ← Server statistics
│       ├── forums.ts        ← Forum channels, posts, tags
│       ├── webhooks.ts      ← Webhook management
│       ├── scheduledEvents.ts ← Scheduled events
│       ├── invites.ts        ← Invite management
│       └── dm.ts             ← Direct messages
├── test/                     ← node:test suite (schemas, gating, allow-list)
├── scripts/                  ← sync-version.js (npm version hook)
├── .github/workflows/        ← CI/CD (build check + auto release)
├── Dockerfile
├── .dockerignore
├── .env.example
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── README.md

添加新工具

1. 在 src/tools/ 中创建一个新文件（例如 events.ts）
2. 使用 defineTool({ name, description, annotations, schema, handle }) 声明每个工具，并将 defineModule([...]) 导出为默认值
3. 导入该模块，并将其添加到 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 即可执行

贡献

欢迎贡献！

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/my-feature）
3. 遵循模块化结构，参见添加新工具
4. 提交更改并发起 pull request

许可证

许可证为 MIT，详情请参见 LICENSE。