AI导哈

BoardGameGeek API客户端库

一个用于与BoardGameGeek API交互的Go客户端库和MCP服务器，支持搜索游戏、浏览收藏、记录游戏过程等功能。

  • by fzerorubigd
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 fzerorubigd/bggo

使用说明

bggo

Go客户端库和MCP服务器 BoardGameGeek API

这是对 gobgg 具有更干净的API设计、基于结构的请求/响应和附加功能。

MCP 服务器

附带的MCP服务器允许AI助手（Claude等）与BoardGameGeek进行交互——搜索游戏、浏览收藏、检查热度、记录游戏等。

先决条件

构建

go install github.com/fzerorubigd/bggo/cmd/bgg-mcp@latest

或者从本地克隆：

git clone https://github.com/fzerorubigd/bggo.git
cd bggo
go build -o bgg-mcp ./cmd/bgg-mcp/

配置

服务器从环境变量中读取配置：

变量 必填 描述
BGG_API_KEY 是 您的BoardGameGeek API密钥
BGG_USERNAME 否 BGG用户名用于经过身份验证的功能（例如记录播放）
BGG_PASSWORD 无 经过身份验证的功能的BGG密码

添加到克劳德代码

claude mcp add bgg-mcp -e BGG_API_KEY=your-key -- /path/to/bgg-mcp

或者具有经过身份验证的功能：

claude mcp add bgg-mcp \
  -e BGG_API_KEY=your-key \
  -e BGG_USERNAME=your-user \
  -e BGG_PASSWORD=your-pass \
  -- /path/to/bgg-mcp

添加到克劳德桌面

将此添加到您的Claude Desktop配置中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux： ~/.config/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "bgg-mcp": {
      "command": "/path/to/bgg-mcp",
      "env": {
        "BGG_API_KEY": "your-key",
        "BGG_USERNAME": "your-user",
        "BGG_PASSWORD": "your-pass"
      }
    }
  }
}

可用工具

工具 说明
search 按名称搜索棋盘游戏
get_things 通过BGG ID获取详细的游戏信息（最多20个）
get_collection 浏览用户的棋盘游戏收藏
get_plays 查看用户或游戏的游戏历史记录
post_play 记录新游戏（需要登录）
get_hotness BGG当前热门游戏
get_geek_list 从极客列表中获取项目
get_best_sellers 每周最畅销游戏
get_most_played 大多数人在一段时间内玩游戏
get_trending_plays 游戏数量增长最多的游戏

Go 库

MCP服务器构建在 bggo Go库，您也可以直接在自己的项目中使用。

安装

go get github.com/fzerorubigd/bggo

用法

client := bggo.NewClient("your-bgg-api-key")

API密钥是必需的，并用作所有请求的承载令牌。

搜索

results, err := client.Search(ctx, bggo.SearchRequest{
    Query: "Catan",
    Types: []bggo.ItemType{bggo.BoardGameType},
    Exact: true,
})

获取物品（游戏详情）

things, err := client.GetThings(ctx, bggo.GetThingsRequest{
    IDs: []int64{13, 30549}, // Catan, Pandemic
})

// With rating breakdown (extra API call per thing)
things, err := client.GetThings(ctx, bggo.GetThingsRequest{
    IDs:           []int64{13},
    RankBreakDown: true,
})

用户档案

user, err := client.GetUser(ctx, bggo.GetUserRequest{
    Username: "someone",
})

收集

items, err := client.GetCollection(ctx, bggo.GetCollectionRequest{
    Username: "someone",
    Statuses: []bggo.CollectionStatus{bggo.CollectionOwn},
})

演奏

plays, err := client.GetPlays(ctx, bggo.GetPlaysRequest{
    Username: "someone",
})

登录和游戏后

err := client.Login(ctx, bggo.LoginRequest{
    Username: "user",
    Password: "pass",
})

result, err := client.PostPlay(ctx, bggo.PostPlayRequest{
    GameID:   23383,
    GameType: "thing",
    Date:     time.Now(),
    Length:   20 * time.Minute,
    Players: []bggo.PostPlayPlayer{
        {Username: "player1", Name: "Alice", Win: true},
    },
})

热门与趋势

hot, err := client.GetHotness(ctx, bggo.GetHotnessRequest{Count: 10})

trend, err := client.GetMostPlayed(ctx, bggo.GetTrendRequest{
    Interval:  bggo.TrendWeek,
    StartDate: time.Now().AddDate(0, 0, -7),
})

极客列表

items, err := client.GetGeekList(ctx, bggo.GetGeekListRequest{
    ListID: 330393,
})

将管道列表导入GetThings

所有列表类型都实现 IDGetter.使用 ExtractIDs 将结果导入 GetThings:

hot, _ := client.GetHotness(ctx, bggo.GetHotnessRequest{Count: 5})
things, _ := client.GetThings(ctx, bggo.GetThingsRequest{
    IDs: bggo.ExtractIDs(hot),
})

客户端选项

client := bggo.NewClient("api-key",
    bggo.WithHTTPClient(customClient),
    bggo.WithHost("boardgamegeek.com"),
    bggo.WithScheme("https"),
    bggo.WithLimiter(rateLimiter), // compatible with go.uber.org/ratelimit
    bggo.WithCookies("user", cookies),
)

许可证

麻省理工学院

相关 MCP