BGG MCP Server in Go for BoardGameGeek Data
Access BoardGameGeek data with an MCP server in Go, retrieve and filter game details, user collections, and profiles using the GoGeek-powered API.
npx -y @kkjdaniel/bgg-mcpOverview
BGG MCP is a Model Context Protocol (MCP) server written in Go that exposes BoardGameGeek (BGG) data to MCP-capable assistants and tools. It wraps the BoardGameGeek API via the GoGeek library to provide reliable retrieval and filtering of game details, user collections, forum threads, and user profiles. The server also enriches results with live price data from BoardGamePrices.co.uk and similarity-based recommendations from Recommend.Games.
For developers building assistants, bots, or integrations that need curated BGG context (search, details, collections, prices, recommendations), BGG MCP provides a consistent, filterable interface that can be hosted locally or in a container and connected to any MCP-aware runtime.
Features
- Exposes BoardGameGeek data through the Model Context Protocol.
- Game search with type filters (base game, expansion, or all).
- Detailed game metadata: stats, mechanics, artists, designers, thumbnails, and images.
- Queryable user collections with advanced filters (rating ranges, players, play status).
- User profile and forum thread retrieval (full thread content).
- Price lookups aggregated from multiple retailers (via BoardGamePrices.co.uk).
- Similarity recommendations powered by Recommend.Games.
- Experimental rules-retrieval tool: search BGG forums to surface rules discussions.
- Small, production-ready Go server using the GoGeek library for robust API interactions.
Installation / Configuration
Prerequisites: Go 1.20+ (or the version indicated in the repository), Docker (optional).
Clone and build locally:
# Run without building (for development)
# Or build a binary
Common environment variables
# Basic configuration
# server port
# optional: enables bgg://my-collection resource
# optional, if using any API keys for price services
Docker
# Example Dockerfile (project may include one already)
FROM golang:1.20-alpine AS build
WORKDIR /src
COPY . .
RUN go build -o /bin/bgg-mcp ./cmd/bgg-mcp
FROM alpine:latest
COPY --from=build /bin/bgg-mcp /bin/bgg-mcp
EXPOSE 8080
ENTRYPOINT ["/bin/bgg-mcp"]
Run:
Note: The repository uses the GoGeek library internally — no special setup is required beyond standard Go tooling and any optional external service keys for price/recommendation providers.
Available Tools
The server exposes multiple MCP “tools” (endpoints) that map to common BGG operations. Typical tool names and descriptions:
| Tool | Purpose |
|---|---|
| bgg-search | Find games by name with optional type filters (base/expansion) |
| bgg-details | Return full metadata for a specific game (by ID or name) |
| bgg-collection | Query a user’s collection with filters (rating, players, status) |
| bgg-hot | Retrieve the current BGG hotness list |
| bgg-user | Fetch public user profile data and summary |
| bgg-price | Aggregate current retailer prices by BGG ID |
| bgg-trade-finder | Compare two users’ collections to find trade opportunities |
| bgg-recommender | Get similarity-based recommendations for a game |
| bgg-thread-details | Download the full content of a forum thread (all posts) |
| bgg-rules (experimental) | Search BGG forums to surface rules clarifications |
Resources available to MCP clients:
| Resource URI | Description |
|---|---|
| bgg://hotness | Always-available hotness list from BGG |
| bgg://my-collection | Your personal collection (requires BGG_USERNAME configured) |
Use Cases
- Build a chat assistant that answers board-game questions with authoritative BGG context. Example: “Show me details for Azul” — the assistant calls bgg-details and returns designers, play time, and rules links.
- Filter a user’s collection for session planning. Example: “List games in my collection playable with 5 players and rated 8+” — use bgg-collection with player and rating filters to generate a shortlist.
- Compare two collectors to find trade candidates. Example: “Find items I can trade to user X to get game Y” — run bgg-trade-finder to compute overlaps and missing items.
- Surface current market prices. Example: “Best UK price for Wingspan” — call bgg-price to get retailer comparisons and lowest available price.
- Produce similarity-based recommendations. Example: “Recommend five games similar to Gloomhaven with at least 1000 ratings” — bgg-recommender returns matches weighted by recommendation provider and BGG approval.
- Research rules questions (experimental). Example: “How does combat resolve in Game Z?” — the bgg-rules tool searches BGG forums and aggregates relevant discussion excerpts.
Example Prompts / API Patterns
Common prompt patterns an assistant would map to tools:
- Search: “Search for ‘Terraforming Mars’ expansions only” → bgg-search (type=expansion)
- Details: “Get details for game ID 167791” → bgg-details (id=167791)
- Collection filter: “Show my unplayed games rated 7+” → bgg-collection (status=unplayed, min_rating=7)
- Price compare: “Compare prices for Wingspan and Ark Nova” → bgg-price (ids=[…])
Where to find it
Repository and source code: https://github.com/kkjdaniel/bgg-mcp
For developers new to MCP, BGG MCP is a practical example of integrating a third-party data source into the MCP ecosystem using Go — providing ready-made tools and resources to enrich conversational agents with board-game context.