cli · mcp server · go library

Your shelf of shame, everywhere you work.

Search games, browse collections, and pull geeklists from your terminal — or hand the same tools to Claude and any other MCP host. Built on a rate-limited, retry-aware Go client for the BoardGameGeek® XML API.

Install View on GitHub

Requires your own free BGG API token — register with BGG to get one.

shelfofshame

$ shelfofshame search "Brass Birmingham" --exact
{
  "boardgames": [{
    "objectId": "224517",
    "yearPublished": 2018,
    "name": { "value": "Brass: Birmingham" }
  }]
}
$ shelfofshame serve  # MCP over stdio

what you get

One binary, three ways in.

Colourful CLI

Syntax-highlighted JSON for search, boardgames, collections, and geeklists. Respects NO_COLOR and pipes cleanly.

MCP server

Four typed tools over stdio or streamable HTTP, built on the official MCP Go SDK. Ask Claude about your collection.

Go library

The xml1 package underneath: context-aware, typed errors, functional options, dual xml/json models.

Polite by default

Built-in rate limiting (one request per 5s), automatic retries on 429 and BGG's 202 "still preparing" responses, and Bearer-token auth.

the cli

Your collection, one command away.

Every endpoint of the BGG XML API 1, with flags for all the filters. Set BGG_API_TOKEN once and go.

# search by name
shelfofshame search "Catan"

# full details, stats included
shelfofshame boardgame 13 224517 --stats

# owned games rated 7+
shelfofshame collection richardwooding \
  --own --min-rating=7

# geeklists, with comments
shelfofshame geeklist 11205 --comments

# plain output for scripts
shelfofshame search "Root" --no-color | jq

# be extra gentle to BGG
shelfofshame --request-interval=10s search "Ark Nova"

the mcp server

Give your assistant a seat at the table.

shelfofshame serve exposes BGG as typed MCP tools — structured output schemas included — over stdio or streamable HTTP.

Tools

search_boardgames
get_boardgames
get_collection
get_geeklist

Search, fetch up to 20 games with stats, filter collections by ownership/rating/plays, and pull geeklists.

# Claude Code
claude mcp add shelfofshame \
  --env BGG_API_TOKEN=your-token \
  -- shelfofshame serve

# or remote, over streamable HTTP
shelfofshame serve --http :8080

the library

The client underneath.

api := xml1.NewAPI(xml1.Options{
    BaseURL:  "https://boardgamegeek.com/xmlapi",
    APIToken: os.Getenv("BGG_API_TOKEN"),
})

games, err := api.SearchBoardgames(ctx, "Catan")
items, err := api.GetCollection(ctx, "user", xml1.Own(true))

Typed all the way down

Functional options per endpoint, typed errors (NotFoundError, TooManyRetriesError, …), and models that marshal to both XML and JSON. Tested offline against a recorded BGG cassette.

pkg.go.dev reference ↗

install

Pick your poison.

First: get your own BGG API token

The BGG XML API only accepts registered applications — without a token every request is rejected with 401 Unauthorized. Registration is free for non-commercial use:

Register your application with BGG (needs a BGG account)
Create an API token on the same page
Export it: export BGG_API_TOKEN=your-token

Play by the rules

Your use of the data is governed by the XML API Terms of Use: the data is licensed for non-commercial purposes, must be credited to BoardGameGeek, and may not be used to train AI/LLM systems. shelfofshame rate-limits itself to stay well within BGG's guidance.

brew brew install richardwooding/tap/shelfofshame

go go install github.com/richardwooding/shelfofshame@latest

oci docker run --rm -e BGG_API_TOKEN ghcr.io/richardwooding/shelfofshame search "Catan"

All game data is sourced from BoardGameGeek and used under the XML API Terms of Use.

BoardGameGeek® and BGG® are registered trademarks of BoardGameGeek, LLC. shelfofshame is an independent project and is not affiliated with, sponsored by, or endorsed by BoardGameGeek.