bgg-mcp - README

bgg-mcp

Overview & quick usage

bgg-mcp is a small Model Context Protocol (MCP) server written in TypeScript that exposes BoardGameGeek (BGG) APIs as MCP tools. It uses the MCP SDK and xml2js to parse BGG's XML APIs and returns human-readable responses. The package compiles to dist/ and includes a small CLI wrapper so it can be executed with npx or npm.

Quick run (local build):

npm ci
npm run build
node dist/index.js

Quick run (npx, GitHub-backed):

npx stevenpfiggins/bgg-mcp

If you publish to npm, npx bgg-mcp will work once the package is published.

What this repo contains

• src/ - TypeScript source (MCP tool registration)
• dist/ - compiled output (generated by npm run build)
• bin/bgg-mcp.js - small CLI wrapper used by the bin entry
• Dockerfile, docker-compose.yml, .dockerignore - docker artifacts
• package.json - build/publish scripts and metadata

Available MCP tools

These tools are registered in src/index.ts. Each returns an object typically shaped like:

{ content: [{ type: 'text', text: '...' }], isError?: true, results?: [...] }

• search_games — Search BGG by free text.

  • Input: { query: string }
  • Output: human-readable text, plus results: [{ id, name, year }, ...] for programmatic use.

• get_game_details — Fetch detailed info for a game.

  • Input: { id: string }

• get_user_collection — Fetch a user's collection with filters.

  • Input: { username: string, subtype?: string, own?: string, rated?: string, played?: string, rating?: string, maxresults?: number }

• get_user_plays — Get a user's plays.

  • Input: { username: string, mindate?: string, maxdate?: string, id?: string }

• get_user_info — Fetch a user's public profile.

  • Input: { name: string }

• get_hot_items — Fetch trending items.

  • Input: { type?: string }

Examples

Below are example mcp.json tool invocation snippets you can use with an MCP host that supports calling registered tools.

1. Search games by query

{
	"tool": "search_games",
	"input": { "query": "catan" }
}

2. Get details for a game id

{
	"tool": "get_game_details",
	"input": { "id": "13" }
}

3. Get a user's collection (first 10 items)

{
	"tool": "get_user_collection",
	"input": { "username": "exampleuser", "maxresults": 10 }
}

4. Get a user's plays in a date range

{
	"tool": "get_user_plays",
	"input": { "username": "exampleuser", "mindate": "2023-01-01", "maxdate": "2023-12-31" }
}

Implementation notes

• Responses are parsed from BGG's XML using xml2js and formatted into text. search_games also exposes structured results for programmatic consumption.
• Most endpoints implement retry logic when BGG responds with HTTP 202 (queued).

Docker & environment (setup)

You can run the server inside Docker. The image uses a multi-stage build so TypeScript is compiled during image build and only production dependencies are installed in the runtime image.

Quick Docker build & run:

docker build -t bgg-mcp:latest . ;
docker run --rm -p 8080:8080 --name bgg-mcp bgg-mcp:latest

Or with docker-compose:

docker compose up --build

Local development tips

• Use npm run build after editing TypeScript sources to refresh dist/.
• For faster iteration you can run the TypeScript directly with tsx or ts-node (devDependency installed). Example:

npm ci
npx tsx src/index.ts

Troubleshooting

• If you see could not determine executable to run when using npx, ensure the package has been published or use the GitHub short-hand npx <owner>/<repo> which installs from the repo.
• If BGG APIs return HTTP 202 (queued), the implementation retries; you may still need to increase retry counts for large collections.

License

MIT — see LICENSE file.