BGG MCP: BoardGameGeek MCP API Server

一个 MCP 服务，让 AI 助手能够访问 BoardGameGeek：游戏详情、收藏、价格、推荐和规则问答。

BGG MCP 通过 Model Context Protocol 提供对 BoardGameGeek API 的访问，以便检索和筛选桌游数据、用户收藏和个人资料。此服务使用 GoGeek 库以 Go 实现，有助于确保 API 交互可靠。

价格数据由 BoardGamePrices.co.uk 提供，可实时获取多家零售商的价格。

游戏推荐由 Recommend.Games 提供支持，基于 BoardGameGeek 数据进行算法相似度推荐。

演示

工具

工具	描述
bgg-search	搜索桌游，并按类型筛选（基础游戏、扩展或全部）
bgg-details	获取游戏详情，包括最佳玩家人数、排名，以及可选的市场列表、版本和用户评论
bgg-collection	查询并筛选用户收藏，包括其评分、BGG 评分、排名和游玩次数
bgg-hot	获取当前 BGG 热门榜单
bgg-user	获取用户个人资料信息
bgg-price	使用 BGG ID 获取多家零售商的当前价格
bgg-trade-finder	查找两位 BGG 用户之间的交易机会
bgg-recommender	根据与指定游戏的相似度获取游戏推荐
bgg-rules	在游戏的 BGG 规则论坛中查找最相关的帖子，以回答规则问题
bgg-thread-details	获取指定 BGG 论坛帖子的完整内容，包括所有帖子

说明

结果会链接回 boardgamegeek.com 上的对应页面，并会提示助手在回答中包含这些链接。

资源

BGG MCP 会公开 AI 助手可直接访问的资源，以获取上下文信息：

资源	URI	描述
BGG Hotness	bgg://hotness	当前的 BGG 热门列表，始终可用
My BGG Collection	bgg://my-collection	你的个人 BGG 收藏（仅当设置了 BGG_USERNAME 时列出）
BGG User Collection	bgg://collection/{username}	任意 BGG 用户收藏中的已拥有游戏
BGG Game	bgg://game/{id}	指定 BGG ID 游戏的基本信息
BGG Forum Thread	bgg://thread/{id}	指定 ID 的 BGG 论坛帖子，包含所有纯文本帖子

提示词

BGG MCP 为常见工作流提供了预配置提示词：

提示词	参数	描述
trade-sales-post	username、currency、destination、discount、platform	为你的 BGG「可交易」收藏生成售卖帖子，价格低于零售价
game-recommendations	username、currency、destination	根据你的 BGG 收藏和偏好获取个性化游戏推荐
rules-question	game、question	根据游戏的 BGG 规则论坛回答规则问题

设置了 BGG_USERNAME 时，这两个提示词中的 username 均为可选参数。

示例提示词

下面是一些可用于与 BGG MCP 工具交互的示例提示词：

🔍 搜索

"Search for Wingspan on BGG"
"How many expansions does Grand Austria Hotel have?"
"Search for Wingspan expansions only"

📊 游戏详情

"Get details for Azul"
"Show me information about game ID 224517"
"What's the BGG rating for Gloomhaven?"
"What is Ark Nova selling for on the BGG marketplace?"
"What expansions does Wingspan have?"

📚 收藏

"Show me ZeeGarcia's game collection"
"Show games rated 9+ in kkjdaniel's collection"
"List unplayed games in rahdo's collection"
"Find games for 6 players in kkjdaniel's collection"
"Show me all the games rated 3 and below in my collection"
"What games in my collection does rahdo want?"
"What games does kkjdaniel have that I want?"
"Which games in my collection play best at 2 players?"

🔥 热门

"Show me the current BGG hotness list"
"What's trending on BGG?"

👤 用户资料

"Show me details about BGG user rahdo"
"When did user ZeeGarcia join BGG?"
"How many buddies do I have on bgg?"

💰 价格

"Get the best price for Wingspan in GBP"
"Show me the best UK price for Ark Nova"
"Compare prices for: Wingspan & Ark Nova"

🎯 推荐

"Recommend games similar to Wingspan"
"What games are like Azul but with at least 1000 ratings?"
"Find 5 games similar to Troyes"

📖 规则

提示

助手经常会凭记忆回答规则问题。请提及 BGG，并明确说明你指的是桌游，以便搜索规则论坛；或者使用 rules-question 提示词。

"Check BGG, in Wingspan do pink powers trigger on my own turn?"
"What does the BGG rules forum say about trading with the bank during another player's turn in Catan?"
"In the board game Root, can the Vagabond attack a player it is allied with? Check BGG"
"Search BGG for how line of sight works in Gloomhaven"

安装

需要身份验证：大多数 BGG MCP 工具都需要身份验证才能访问 BoardGameGeek 的 API。设置说明请参阅下方的配置部分。

A) Claude Desktop Extension（macOS / Windows）（推荐）

从最新版本下载 bgg-mcp.mcpb 并双击。Claude Desktop 会打开安装对话框，你可以在其中输入 BGG API 密钥和用户名，无需 Docker 或 Go。

B) Smithery（macOS / Windows）

BGG MCP 也发布在 Smithery 上，它分发相同的安装包，因此服务会在你的电脑上本地运行。打开服务页面，选择你的客户端并按照安装步骤操作，在配置表单中输入 BGG API 密钥和用户名。

C) Docker

BGG MCP 已发布到 Docker Hub，并列入 MCP Registry。将以下内容添加到 claude_desktop_config.json（Claude Desktop）或 settings.json（VS Code / Cursor）中：

"bgg": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "--pull=always",
        "-e", "BGG_API_KEY",
        "-e", "BGG_USERNAME",
        "kdaniel/bgg-mcp"
    ],
    "env": {
        "BGG_API_KEY": "your_api_key_here",
        "BGG_USERNAME": "your_bgg_username"
    }
}

有关如何获取 BGG API 密钥并设置用户名的详细信息，请参阅下文的配置。

--pull=always 会在服务每次启动时获取最新镜像，让你自动保持最新。如果需要离线启动服务，请移除此参数。

有关将 MCP 服务连接到客户端的更多详情，请参阅 MCP 官方指南。

D) 手动设置

1. 安装 Go

你需要在系统上安装 Go 才能构建二进制文件。你可以轻松地在此处下载并安装，也可以使用自己偏好的软件包管理器，例如 Brew。

2. 构建

项目包含一个 Makefile，可简化二进制文件的构建和管理。

# Build the application (output goes to build/bgg-mcp)
make build

# Clean build artifacts
make clean

# Both clean and build
make all

或者，你也可以直接使用 Go 构建……

go build -o build/bgg-mcp

3. 添加 MCP 配置

在 settings.json（VS Code / Cursor）或 claude_desktop_config.json 中，将以下内容添加到服务器列表，并将路径指向你之前创建的二进制文件。启动 AI 工具后，你应该能看到该服务提供的工具已连接：

"bgg": {
    "command": "path/to/build/bgg-mcp",
    "args": ["-mode", "stdio"]
}

有关配置 Claude 的更多详情，请参阅此处。

配置

身份验证

BGG MCP 使用 GoGeek v3 库，该库要求进行身份验证才能访问 BoardGameGeek 的 API。

你可以使用 BGG_API_KEY（推荐）或 BGG_COOKIE 配置身份验证：

身份验证设置

选项 1：API 密钥（推荐）

从 BoardGameGeek 的 API 申请表获取 API 密钥，并将其添加到配置中：

"bgg": {
    "env": {
        "BGG_API_KEY": "your_api_key_here"
    }
}

选项 2：Cookie 身份验证

或者，你也可以使用基于 Cookie 的身份验证：

"bgg": {
    "env": {
        "BGG_COOKIE": "bggusername=user; bggpassword=pass; SessionID=xyz"
    }
}

注意：如果两者都已提供，默认将使用 BGG_API_KEY。

用户名配置

你可以选择设置 BGG 用户名，这样查询中就可以使用“我”和“我的”指代，而无需明确写出用户名。

如果你安装了 Claude Desktop 扩展（macOS / Windows，推荐），请在 Claude Desktop 的扩展设置中（Settings > Extensions > BGG MCP）输入用户名，你也可以在此处设置 API 密钥。无需编辑配置文件。如果你通过 Smithery（macOS / Windows）安装，配置表单会要求你填写用户名和 API 密钥。

对于 Docker 或手动设置，请设置 BGG_USERNAME 环境变量：

"bgg": {
    "env": {
        "BGG_USERNAME": "your_bgg_username",
        "BGG_API_KEY": "your_api_key_here"
    }
}

这样即可启用：

• 收藏查询：使用“显示我的收藏”，无需指定用户名
• 用户查询：使用“显示我的 BGG 个人资料”
• AI 助手：AI 可以在比较和分析时自动使用你的用户名

注意：如果使用自我指代（我、我的）但未设置用户名，你会收到清晰的错误消息。

更新通知

在你的机器上运行时，BGG MCP 每天会检查一次 GitHub 是否有较新版本。如果有，助手会在每次对话中提及一次，并附上版本发布链接。将 BGG_DISABLE_UPDATE_CHECK 设为 true 即可关闭此功能。服务以 HTTP 模式运行时绝不会进行检查。