内容
<p align="center">
<img src="images/bgg-mcp-logo.png" width="200" alt="BGG MCP Logo">
</p>
<h1 align="center">BGG MCP: BoardGameGeek MCP 服务器</h1>
<p align="center">
<a href="https://archestra.ai/mcp-catalog/kkjdaniel__bgg-mcp"><img src="https://archestra.ai/mcp-catalog/api/badge/quality/kkjdaniel/bgg-mcp" alt="信任度徽章"></a>
<a href="https://github.com/modelcontextprotocol/registry"><img src="https://img.shields.io/badge/MCP_Registry-BGG_MCP-green" alt="MCP 注册表"></a>
<br>
<a href="https://go.dev/"><img src="https://img.shields.io/github/go-mod/go-version/kkjdaniel/bgg-mcp" alt="Go 版本"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/kkjdaniel/bgg-mcp" alt="许可证"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Protocol-blue" alt="MCP 协议"></a>
</p>
BGG MCP 通过 [模型上下文协议](https://www.anthropic.com/news/model-context-protocol) 提供对 BoardGameGeek API 的访问，使检索和过滤棋盘游戏数据、用户收藏和个人资料成为可能。服务器使用 Go 实现，使用 [GoGeek](https://github.com/kkjdaniel/gogeek) 库，确保稳健的 API 交互。
价格数据由 [BoardGamePrices.co.uk](https://boardgameprices.co.uk) 提供，实时价格来自多家零售商。
游戏推荐由 [Recommend.Games](https://recommend.games/) 提供，基于 BoardGameGeek 数据提供算法相似性推荐。
<a href="https://boardgamegeek.com/">
<img src="images/powered-bgg.webp" width="160" alt="Powered by BGG">
</a>
## 演示
<div align="center">
[](https://youtu.be/cNX4WwVbFko)
**[▶️ 观看规则工具演示视频](https://youtu.be/cNX4WwVbFko)**
</div>
## 工具
### 核心工具
| 工具 | 描述 |
| -------------------- | --------------------------------------------------------------------------- |
| `bgg-search` | 搜索棋盘游戏，类型过滤（基础游戏、扩展或所有） |
| `bgg-details` | 获取特定棋盘游戏的详细信息 |
| `bgg-collection` | 查询和过滤用户的游戏收藏，具备广泛的过滤选项 |
| `bgg-hot` | 获取当前的 BGG 热点列表 |
| `bgg-user` | 获取用户信息 |
| `bgg-price` | 使用 BGG ID 从多家零售商获取当前价格 |
| `bgg-trade-finder` | 在两个 BGG 用户之间查找交易机会 |
| `bgg-recommender` | 根据特定游戏的相似度获取游戏推荐 |
| `bgg-thread-details` | 获取特定 BGG 论坛线程的完整内容，包括所有帖子 |
### 🧪 实验性工具
| 工具 | 描述 |
| ----------- | ------------------------------------------------------------------------------------------ |
| `bgg-rules` | 通过搜索 BGG 论坛的相关讨论和澄清来回答规则问题 |
## 资源
BGG MCP 公开资源，AI 助手可以直接访问以获取上下文信息：
| 资源 | URI | 描述 |
| ------------------- | --------------------- | ---------------------------------------------------------------- |
| `BGG 热点` | `bgg://hotness` | 当前的 BGG 热点列表，始终可用 |
| `我的 BGG 收藏` | `bgg://my-collection` | 个人 BGG 收藏（需要设置 `BGG_USERNAME`） |
## 提示
BGG MCP 包含预配置的提示，用于常见的工作流程：
| 提示 | 描述 |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `交易销售帖` | 为 BGG 的“待交易”收藏生成格式化的销售帖，附带折扣市场价格 |
| `游戏推荐` | 根据 BGG 收藏和偏好获取个性化的游戏推荐 |
## 示例提示
以下是一些示例提示，您可以使用它们与 BGG MCP 工具交互：
### 🔍 搜索
```
"在 BGG 上搜索 Wingspan"
"Grand Austria Hotel 有多少个扩展？"
"仅搜索 Wingspan 的扩展"
```
### 📊 游戏详情
```
"获取 Azul 的详细信息"
"显示游戏 ID 224517 的信息"
"Gloomhaven 的 BGG 评分是多少？"
```
### 📚 收藏
```
"显示 ZeeGarcia 的游戏收藏"
"显示 kkjdaniel 收藏中评分 9+ 的游戏"
"列出 rahdo 收藏中未玩的游戏"
"在 kkjdaniel 的收藏中找到 6 名玩家的游戏"
"显示我收藏中评分 3 及以下的游戏"
"rahdo 想要什么游戏在我的收藏中？"
"kkjdaniel 有什么游戏是我想要的？"
```
### 🔥 热点
```
"显示当前的 BGG 热点列表"
"BGG 上有什么流行趋势？"
```
### 👤 用户资料
```
"显示 BGG 用户 rahdo 的资料"
"ZeeGarcia 何时加入 BGG？"
"我在 BGG 上有多少个好友？”
```
### 💰 价格
```
"获取 Wingspan 在 GBP 中的最佳价格"
"显示 Ark Nova 在英国的最佳价格"
"比较价格：Wingspan & Ark Nova"
```
### 🎯 推荐
```
"推荐与 Wingspan 类似的游戏"
"有哪些游戏类似于 Azul 但至少有 1000 条评分？"
"找到 5 款与 Troyes 类似的游戏"
```
### 📖 规则（实验性）
```
"[关于任何棋盘游戏的规则问题] - 使用 bgg-rules"
"[游戏机制] 在 [游戏名称] 中如何工作？使用 bgg-rules"
"我可以在 [游戏名称] 中 [特定操作] 吗？使用 bgg-rules"
"[游戏名称] 中出现 [情况] 时会发生什么？使用 bgg-rules"
```
注意：在问题中包含“使用 bgg-rules”，以确保 AI 在 BGG 论坛中搜索答案。
## 安装
> **身份验证要求**：大多数 BGG MCP 工具需要身份验证才能访问 BoardGameGeek 的 API。请参阅下面的 [配置部分](#configuration) 以获取设置说明。
### A) Docker（推荐）
BGG MCP 发布到 [Docker Hub](https://hub.docker.com/r/kdaniel/bgg-mcp) 并列在 [MCP 注册表](https://github.com/modelcontextprotocol/registry) 中。将以下内容添加到您的 `claude_desktop_config.json`（Claude Desktop）或 `settings.json`（VS Code / Cursor）：
```json
"bgg": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "BGG_API_KEY",
"-e", "BGG_USERNAME",
"kdaniel/bgg-mcp"
],
"env": {
"BGG_API_KEY": "您的 API 密钥",
"BGG_USERNAME": "您的 BGG 用户名"
}
}
```
> 请参阅 [配置](#configuration) 以获取有关获取 BGG API 密钥和设置用户名的详细信息。
有关将 MCP 服务器连接到客户端的更多详细信息，请参阅 [官方 MCP 指南](https://modelcontextprotocol.io/docs/develop/connect-local-servers)。
### B) 手动设置
#### 1. 安装 Go
您需要在系统上安装 Go 以构建二进制文件。可以 [在此处下载和设置](https://go.dev/doc/install)，或者使用您喜欢的包管理器（如 Brew）。
#### 2. 构建
项目包含一个 Makefile 以简化构建和管理二进制文件。
```bash
# 构建应用程序（输出到 build/bgg-mcp）
make build
# 清理构建工件
make clean
# 两者都清理和构建
make all
```
或者，您可以直接使用 Go 构建：
```bash
go build -o build/bgg-mcp
```
#### 3. 添加 MCP 配置
在 `settings.json`（VS Code / Cursor）或 `claude_desktop_config.json` 中添加以下内容，指向您之前创建的二进制文件，一旦您加载 AI 工具，您应该会看到服务器提供的工具：
```json
"bgg": {
"command": "path/to/build/bgg-mcp",
"args": ["-mode", "stdio"]
}
```
更多配置 Claude 的详细信息可以在 [此处](https://modelcontextprotocol.io/quickstart/user) 找到。
## 配置
### 身份验证
BGG MCP v2.0+ 使用 GoGeek v2.0 库，该库需要身份验证才能可靠地访问 BoardGameGeek 的 API。
您可以使用 **以下任一方式** 配置身份验证：`BGG_API_KEY`（推荐）或 `BGG_COOKIE`:
#### 身份验证设置
##### 选项 1：API 密钥（推荐）
从 [BoardGameGeek 的 API 申请表](https://boardgamegeek.com/applications) 获取 API 密钥，并将其添加到您的配置中：
```json
"bgg": {
"env": {
"BGG_API_KEY": "您的 API 密钥"
}
}
```
##### 选项 2：Cookie 身份验证
或者，您可以使用基于 Cookie 的身份验证：
```json
"bgg": {
"env": {
"BGG_COOKIE": "bggusername=user; bggpassword=pass; SessionID=xyz"
}
}
```
**注意**：如果两者都提供，默认情况下将使用 `BGG_API_KEY`。
### 用户名配置
您可以选择设置 `BGG_USERNAME` 环境变量，以便在查询中启用“me”和“my”的引用，而无需明确说明用户名：
```json
"bgg": {
"env": {
"BGG_USERNAME": "您的 BGG 用户名",
"BGG_API_KEY": "您的 API 密钥"
}
}
```
这使得：
- **收藏查询**： “显示我的收藏”而不是指定用户名
- **用户查询**： “显示我的 BGG 个人资料”
- **AI 助手**： AI 可以自动使用您的用户名进行比较和分析
**注意**：当您在未设置 BGG_USERNAME 的情况下使用自引用（me, my, I）时，您将收到明确的错误消息。
