Bgg MCP Server

🚀 BoardGameGeek MCP Server

This is a Model Context Protocol (MCP) server integrating the BoardGameGeek XML API, allowing Claude to search for board games, retrieve game details, fetch user collections, and perform other functions.

🚀 Quick Start

The BoardGameGeek MCP Server is an integration of the BoardGameGeek XML API, enabling Claude to access a wide range of board game - related information.

✨ Features

This server offers the following tools:

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

Feature List

• [x] Search
• [x] Get game details
• [x] Hot games
• [ ] Get user play records
• [ ] Sync user play records
• [ ] Get user collection
• [ ] Sync user collection
• [ ] Get similar games

📦 Installation

Prerequisites

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

Building and Running the Server

To build the server:

# Install dependencies
npm install

# Build TypeScript code
npm run build

Run the server directly:

# Requires the --experimental-sqlite flag
node --experimental-sqlite build/index.js

Run using Docker:

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

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

💻 Usage Examples

Basic Usage

Testing the Server

To verify if the server is running correctly:

# Ensure the server is built
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 function.
3. Test the get - hot - games function.
4. Display results and any errors.

Advanced Usage

Using with Claude for Desktop

1. Open your Claude for Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration to be executed directly via Node.js:

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

3. 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 flag is used to mount the data directory to ensure data persistence.

4. Restart or reload the Claude application to apply the configuration.

📚 Documentation

Configuration Example

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

Command Example

# Build the project
npm install && npm run build

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

# Run using Docker
docker build -t bgg-mcp-server . && docker run --rm -i bgg-mcp-server

⚠️ Important Note

• Ensure that Node.js and npm are correctly installed.
• When using Docker, you may need to adjust the mount path to ensure data persistence.
• The test script may generate additional logs or output. Check the console for more information.

By following the above steps, you can successfully set up and run the BoardGameGeek MCP Server and integrate it with Claude.