内容
# discord-guild-mcp
一款只读的 [MCP](https://modelcontextprotocol.io) 服务器，使 Claude 可以访问 Discord 服务器的结构：频道、角色、成员和最近的消息历史。
它没有机器人存在，没有网关连接，也没有斜杠命令。它是一个查询层：Claude 调用一个工具，服务器向 Discord 发出 REST 调用，Claude 获取数据返回。它从不发布消息或修改服务器。
## 工具列表
| 工具 | 返回 |
|------|---------|
| `get_guild_info()` | 服务器名称，描述，成员数量，功能标志 |
| `list_channels()` | 所有频道按类别分组，类型和主题 |
| `get_channel(channel_id)` | 一个频道的详细信息：论坛标签，线程数量/存档状态 |
| `list_roles()` | 所有角色，名称，颜色，位置，可提及标志 |
| `list_members(limit=100)` | 最多 `limit` 名成员，用户名，角色，加入日期 |
| `search_members(query, limit=25)` | 用户名/昵称以 `query` 开头的成员 |
| `get_member(user_id)` | 单个成员的用户名，显示名称，角色，加入日期 |
| `get_channel_messages(channel_id, limit=25)` | 频道的最近消息 |
| `get_pinned_messages(channel_id)` | 频道中的所有置顶消息 |
| `list_active_threads(channel_id=None)` | 服务器范围的活动线程，或在一个父频道下 |
| `list_archived_threads(channel_id, limit=50)` | 频道下的最多 `limit` 个已归档公共线程 |
| `list_emojis()` | 服务器的自定义表情符号 |
| `list_scheduled_events()` | 服务器的计划事件，时间，状态，感兴趣的计数 |
### 论坛和线程
论坛频道不直接保存消息，帖子存活在每个主题的线程中。在论坛频道的 ID 上调用 `get_channel_messages()` 返回一个空列表。要读取论坛帖子：调用 `list_active_threads(channel_id)` 和/或 `list_archived_threads(channel_id)` 获取线程 ID，然后在每个线程上调用 `get_channel_messages(thread_id)` （线程是 Discord API 中的频道，因此使用相同的工具）。
## 先决条件
您需要一个现有的 Discord 机器人应用程序（此应用程序与 chikbot-py 使用相同的机器人，或者您可以在 [Discord 开发者门户](https://discord.com/developers/applications) 注册一个新的机器人应用程序）。
机器人必须已经是目标服务器的成员。注册应用程序不会将其添加到您的服务器：这需要 OAuth2 邀请，在机器人最初设置时执行一次。
在该机器人应用程序上，启用两个特权意图（**Bot** 标签在开发者门户中）：
- **服务器成员意图**：`list_members` 所需
- **消息内容意图**：`get_channel_messages` 所需
您还需要：
- 机器人令牌（**Bot** 标签 → 重置/复制令牌）
- 服务器 ID（在 Discord 的用户设置中启用开发者模式 → 高级，然后右键单击服务器图标 → 复制服务器 ID）
## 设置
服务器在 Docker 中运行。Claude Code 为每个会话创建一个新的容器，通过 stdio 运行，因此没有持久的进程，也不需要管理本地 Python 环境。
克隆或更改代码后构建镜像：
```bash
cd discord-guild-mcp
docker build -t discord-guild-mcp .
```
仅当 `config.py`、`discord_client.py`、`server.py` 或 `requirements.txt` 更改时，才需要重新构建。编辑服务器 ID 或令牌不需要重新构建：这些是运行时环境变量，而不是构建到镜像中的。
### 手动本地测试（可选）
直接运行服务器并确认它在不通过 Claude Code 的情况下启动：
```bash
cp .env.example .env
# 填写 DISCORD_BOT_TOKEN 和 DISCORD_GUILD_ID
docker compose run --rm mcp
```
## 在 Claude Code 中注册
MCP 服务器通过 `claude mcp add` CLI 注册，而不是手动编辑 `settings.json`。在用户范围内注册服务器，以便在每个项目中都可用：
```bash
claude mcp add discord-guild -s user -e DISCORD_BOT_TOKEN=your_token_here -e DISCORD_GUILD_ID=your_guild_id_here -- docker run -i --rm -e DISCORD_BOT_TOKEN -e DISCORD_GUILD_ID discord-guild-mcp
```
`docker run` 命令中的裸 `-e KEY` 标志（无 `=value`）会将环境变量从生成的进程环境中转发到容器中，Claude Code 从 `env` 块中设置环境变量。
在 Claude Code 中运行 `/mcp` 以确认它显示为已连接。
### 查询多个服务器
由于服务器 ID 只是一个环境变量，因此同一个镜像可以注册多次，使用不同的名称查询不同的服务器：
```bash
claude mcp add discord-guild-2 -s user -e DISCORD_BOT_TOKEN=your_token_here -e DISCORD_GUILD_ID=other_guild_id -- docker run -i --rm -e DISCORD_BOT_TOKEN -e DISCORD_GUILD_ID discord-guild-mcp
```
Claude 将从您按名称引用的服务器调用工具（例如“使用 discord-guild-2 列出频道”）。
## 项目布局
```
server.py FastMCP 应用；所有工具定义；入口点
discord_client.py 所有 Discord REST 调用；薄异步 HTTP 包装器
config.py 环境加载与启动验证
Dockerfile 服务器镜像构建
docker-compose.yml 本地构建/运行便捷方式，用于手动测试
requirements.txt
.env.example
```
