bgg mcp server

This is a Model Context Protocol (MCP) server that integrates with the BoardGameGeek XML API, allowing Claude to search for board games, retrieve game details, get user collections, and more.

Features

This server provides the following tools:

1. search-games: Search for board games by name
2. get-game-details: Get detailed information about a specific board game
3. get-hot-games: Get the current hottest board games on BoardGameGeek
4. get-user-collection: Get a user's board game collection with filtering options
5. sync-user-collection: Synchronize a user's collection from BoardGameGeek
6. get-user-plays: Get a user's recent board game plays
7. sync-user-plays: Synchronize a user's plays from BoardGameGeek
8. get-similar-games: Get games similar to a specified game

Feature Checklist

• Search
• Get Game Details
• Hot Games
• Get User Plays
• Sync User Plays
• Get User Collection
• Sync User Collection
• Get Similar Games

Prerequisites

• Node.js 22.5.0 or higher (required for experimental SQLite support)
• npm (for dependency management)

Building and Running

To build the server:

# Install dependencies
npm install

# Build the TypeScript code
npm run build

To run the server directly:

# The --experimental-sqlite flag is required
node --experimental-sqlite build/index.js

To run with Docker:

# Build the Docker image
docker build -t bgg-mcp-server .

# Run the container
docker run --rm -i bgg-mcp-server

Testing

To verify the server is working correctly:

# Make sure the server is built first
npm run build

# Run the test script with the experimental SQLite flag
node --experimental-sqlite test-mcp.js

The test script will: 1. Start the MCP server 2. Test the search-games functionality 3. Test the get-hot-games functionality 4. Display results and any errors

Using with Claude for Desktop

1. Open your Claude for Desktop configuration file:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows: %APPDATA%Claudeclaude_desktop_config.json

4. Add the server configuration for direct Node.js execution:

{
  "mcpServers": {
    "boardgamegeek": {
      "command": "node",
      "args": ["--experimental-sqlite", "/path/to/bgg-mcp-server/build/index.js"]
    }
  }
}

1. Or use Docker (recommended):

{
  "mcpServers": {
    "boardgamegeek": {
      "command": "bash",
      "args": ["-c", "cd /path/to/bgg-mcp-server && docker build -t bgg-mcp-server . && docker run --rm -i -v "$(pwd)/data:/app/data" bgg-mcp-server"]
    }
  }
}

Note: the -v "$(pwd)/data:/app/data" option mounts the local data directory to the /app/data directory in the Docker container, ensuring that the SQLite database is persisted outside the container.

1. Restart Claude for Desktop

Example Questions

Once connected to Claude, you can ask questions like:

• "What are the new hot games on boardgamegeek"
• "Look up the game Molly House on boardgamegeek"

Data Storage

The server uses SQLite for data persistence. All retrieved game data, user collections, and play history are stored in the data/bgg.sqlite database file. This:

• Reduces API calls to BoardGameGeek
• Improves response times for repeated queries
• Maintains data between server restarts

The database is automatically created if it doesn't exist and will be populated as you use the server.