tabletopdb

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.

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).

Tool	Arguments	What it does
bgg-search	query (required), type	Search BGG by name. type defaults to boardgame.
bgg-details	id (number, required), type	Full thing details with stats (/thing?id=&stats=1).
bgg-collection	username (required)	A user's owned collection (own=1&stats=1). If BGG answers HTTP 202 (collection being prepared), returns {status: "accepted", note} instead of an error — retry shortly.
bgg-hot	type	The current BGG hot list. type defaults to boardgame.
bgg-user	username (required)	A BGG user profile.
bgg-price	id (number, required)	Resolves the game's identity via BGG and returns {id, name, price_sources: [], note}. Live price lookup needs a separate price-data provider; see Gaps.
bgg-trade-finder	username (required), maxResults	Collection items whose status is marked fortrade, as {username, for_trade, count}.
bgg-recommender	id (number, required), limit	Category heuristic: takes the game's first category, searches it, and returns up to limit other games (default 10). See Gaps.
bgg-rules	id (number, required)	{id, name, description, bgg_url, note} — the game's BGG description and page link. Full rules live in BGG files/wiki.
bgg-thread-details	threadId (number, required)	A forum thread with its parsed articles.

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.