tabletopdb

BoardGameGeek tools for agents: search the BGG catalogue, pull game details and collections, check the hot list, find trades, and get recommendations — all through the public BoardGameGeek XML API2.

tabletopdb is a clean-room rebuild of the documented bgg-mcp tool set (originally by kkjdaniel), written fresh from its public README tool list. It reproduces the tool surface and the request/response handling against the BGG XML API2; it does not copy the original project's code.

One bin serves two faces:

• a small CLI: tabletopdb <tool-name> '<json-arguments>'

• a stdio MCP server: tabletopdb mcp

Requirements

• Node.js 20 or newer.

• A BoardGameGeek API key in the environment:

export BGG_API_KEY="your-bgg-api-key"

Every call sends Authorization: Bearer $BGG_API_KEY. When the key is missing or blank, calls fail with an error naming BGG_API_KEY before any request is made.

Optional environment variables:

• BGG_API_URL — override the API base (default https://boardgamegeek.com/xmlapi2).

• BGG_USERNAME — your BGG username; enriches bgg-price identity output only.

Related MCP server: boardgames

CLI usage

Tool names are hyphenated, exactly as documented:

tabletopdb bgg-search '{"query":"Catan"}'
tabletopdb bgg-details '{"id":13}'
tabletopdb bgg-collection '{"username":"someuser"}'
tabletopdb bgg-hot '{}'
tabletopdb bgg-user '{"username":"someuser"}'
tabletopdb bgg-price '{"id":13}'
tabletopdb bgg-trade-finder '{"username":"someuser","maxResults":10}'
tabletopdb bgg-recommender '{"id":13,"limit":5}'
tabletopdb bgg-rules '{"id":13}'
tabletopdb bgg-thread-details '{"threadId":123456}'
tabletopdb --version

Exit codes: 0 success, 1 API/validation error, 2 usage error (unknown command or malformed JSON arguments).

MCP usage

npx -y @reneturcios/tabletopdb mcp

MCP client config:

{
  "mcpServers": {
    "tabletopdb": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tabletopdb", "mcp"],
      "env": { "BGG_API_KEY": "your-bgg-api-key" }
    }
  }
}

Docker:

docker run -i -e BGG_API_KEY="your-bgg-api-key" ghcr.io/cloudcorprecords/tabletopdb
docker run --rm -e BGG_API_KEY="your-bgg-api-key" ghcr.io/cloudcorprecords/tabletopdb bgg-hot '{}'

Tools

BGG answers in XML; responses are converted to JSON by a small built-in parser (attributes become fields, repeated elements become arrays, element text is kept under a value key where mixed).

Gaps

• bgg-price is an identity shaping, not a price feed: the original project resolves prices through external price sources that its README does not specify, so this rebuild returns the BGG-resolved identity with an empty price_sources list and an explicit note.

• bgg-rules is an info shaping for the same reason: it returns the game's description and canonical BGG page; the full rules live in the files and wiki on that page.

• bgg-recommender is a labelled category heuristic (shared first category, source game excluded), not a learned recommendation model.

• The collection HTTP 202 semantics are simplified to a single {status: "accepted", note} object; callers poll by retrying.

• No live BGG call was made while building this package; behaviour is verified against fake-fetch fixtures only.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.