BGG MCP

O MCP BGG permite que ferramentas de IA interajam com a API do BoardGameGeek.

Documentação

BGG MCP: BoardGameGeek MCP Server

O BGG MCP fornece acesso à API do BoardGameGeek por meio do Model Context Protocol, permitindo recuperação e filtragem de dados de jogos de tabuleiro, coleções de usuários e perfis. O servidor é implementado em Go, usando a biblioteca GoGeek, que ajuda a garantir interações robustas com a API.

Os dados de preços são fornecidos pela BoardGamePrices.co.uk, oferecendo preços em tempo real de vários varejistas.

As recomendações de jogos são fornecidas pela Recommend.Games, que oferece recomendações algorítmicas de similaridade com base nos dados do BoardGameGeek.

Demonstração

▶️ Assista ao Vídeo de Demonstração da Ferramenta de Regras

Ferramentas

Ferramentas Principais

Ferramenta	Descrição
`bgg-search`	Pesquisar jogos de tabuleiro com filtro por tipo (jogos base, expansões ou todos)
`bgg-details`	Obter informações detalhadas sobre um jogo de tabuleiro específico
`bgg-collection`	Consultar e filtrar a coleção de jogos de um usuário com opções abrangentes de filtragem
`bgg-hot`	Obter a lista atual de jogos em alta (hotness) do BGG
`bgg-user`	Obter informações do perfil do usuário
`bgg-price`	Obter preços atuais de vários varejistas usando IDs do BGG
`bgg-trade-finder`	Encontrar oportunidades de troca entre dois usuários do BGG
`bgg-recommender`	Obter recomendações de jogos com base na similaridade com um jogo específico
`bgg-thread-details`	Obter o conteúdo completo de um tópico específico do fórum do BGG, incluindo todas as postagens

🧪 Ferramentas Experimentais

Ferramenta	Descrição
`bgg-rules`	Responder perguntas sobre regras pesquisando nos fóruns do BGG por discussões e esclarecimentos relevantes

Recursos

O BGG MCP expõe recursos que assistentes de IA podem acessar diretamente para obter informações contextuais:

Recurso	URI	Descrição
`BGG Hotness`	`bgg://hotness`	Lista atual de jogos em alta (hotness) do BGG, sempre disponível
`My BGG Collection`	`bgg://my-collection`	Sua coleção pessoal do BGG (requer que `BGG_USERNAME` esteja definido)

Prompts

O BGG MCP inclui prompts pré-configurados para fluxos de trabalho comuns:

Prompt	Descrição
`Trade Sales Post`	Gerar uma publicação de venda formatada para sua coleção de "troca" (for trade) do BGG com preços de mercado com desconto
`Game Recommendations`	Obter recomendações personalizadas de jogos com base na sua coleção e preferências do BGG

Exemplos de Prompts

Aqui estão alguns exemplos de prompts que você pode usar para interagir com as ferramentas do BGG MCP:

🔍 Pesquisa

"Search for Wingspan on BGG"
"How many expansions does Grand Austria Hotel have?"
"Search for Wingspan expansions only"

📊 Detalhes do Jogo

"Get details for Azul"
"Show me information about game ID 224517"
"What's the BGG rating for Gloomhaven?"

📚 Coleção

"Show me ZeeGarcia's game collection"
"Show games rated 9+ in kkjdaniel's collection"
"List unplayed games in rahdo's collection"
"Find games for 6 players in kkjdaniel's collection"
"Show me all the games rated 3 and below in my collection"
"What games in my collection does rahdo want?"
"What games does kkjdaniel have that I want?"

🔥 Em Alta (Hotness)

"Show me the current BGG hotness list"
"What's trending on BGG?"

👤 Perfil do Usuário

"Show me details about BGG user rahdo"
"When did user ZeeGarcia join BGG?"
"How many buddies do I have on bgg?"

💰 Preços

"Get the best price for Wingspan in GBP"
"Show me the best UK price for Ark Nova"
"Compare prices for: Wingspan & Ark Nova"

🎯 Recomendações

"Recommend games similar to Wingspan"
"What games are like Azul but with at least 1000 ratings?"
"Find 5 games similar to Troyes"

📖 Regras (Experimental)

"[Your rules question about any board game] - use bgg-rules"
"How does [game mechanic] work in [game name]? use bgg-rules"
"Can I [specific action] in [game name]? use bgg-rules"
"What happens when [situation] in [game name]? use bgg-rules"

Nota: Inclua "use bgg-rules" na sua pergunta para garantir que a IA pesquise nos fóruns do BGG por respostas.

Instalação

Autenticação Necessária: A maioria das ferramentas do BGG MCP requer autenticação para acessar a API do BoardGameGeek. Consulte a seção de Configuração abaixo para instruções de configuração.

A) Docker (Recomendado)

O BGG MCP é publicado no Docker Hub e listado no MCP Registry. Adicione o seguinte ao seu claude_desktop_config.json (Claude Desktop) ou settings.json (VS Code / Cursor):

"bgg": {
    "command": "docker",
    "args": ["run", "-i", "--rm",
        "-e", "BGG_API_KEY",
        "-e", "BGG_USERNAME",
        "kdaniel/bgg-mcp"
    ],
    "env": {
        "BGG_API_KEY": "your_api_key_here",
        "BGG_USERNAME": "your_bgg_username"
    }
}

Consulte Configuração abaixo para obter detalhes sobre como obter uma chave da API do BGG e configurar seu nome de usuário.

Para mais detalhes sobre como conectar servidores MCP ao seu cliente, consulte o guia oficial do MCP.

B) Configuração Manual

1. Instalar o Go

Você precisará ter o Go instalado no seu sistema para compilar o binário. Ele pode ser facilmente baixado e configurado aqui, ou você pode usar o gerenciador de pacotes de sua preferência, como o Homebrew.

2. Compilar

O projeto inclui um Makefile para simplificar a compilação e o gerenciamento do binário.

# Build the application (output goes to build/bgg-mcp)
make build

# Clean build artifacts
make clean

# Both clean and build
make all

Ou você pode simplesmente compilá-lo diretamente com o Go...

go build -o build/bgg-mcp

3. Adicionar Configuração do MCP

No settings.json (VS Code / Cursor) ou claude_desktop_config.json, adicione o seguinte à sua lista de servidores, apontando para o binário que você criou anteriormente. Ao carregar sua ferramenta de IA, você deverá ver as ferramentas fornecidas pelo servidor conectado:

"bgg": {
    "command": "path/to/build/bgg-mcp",
    "args": ["-mode", "stdio"]
}

Mais detalhes sobre a configuração do Claude podem ser encontrados aqui.

Configuração

Autenticação

O BGG MCP v2.0+ usa a biblioteca GoGeek v2.0, que requer autenticação para acesso confiável à API do BoardGameGeek.

Você pode configurar a autenticação usando ou BGG_API_KEY (recomendado) ou BGG_COOKIE:

Configuração de Autenticação

Opção 1: Chave da API (Recomendado)

Obtenha uma chave da API por meio do formulário de aplicação da API do BoardGameGeek e adicione-a à sua configuração:

"bgg": {
    "env": {
        "BGG_API_KEY": "your_api_key_here"
    }
}

Opção 2: Autenticação por Cookie

Alternativamente, você pode usar autenticação baseada em cookies:

"bgg": {
    "env": {
        "BGG_COOKIE": "bggusername=user; bggpassword=pass; SessionID=xyz"
    }
}

Nota: Se ambos forem fornecidos, BGG_API_KEY será usado por padrão.

Configuração do Nome de Usuário

Você pode opcionalmente definir a variável de ambiente BGG_USERNAME para habilitar referências a "me" e "my" em consultas, sem precisar declarar explicitamente seu nome de usuário:

"bgg": {
    "env": {
        "BGG_USERNAME": "your_bgg_username",
        "BGG_API_KEY": "your_api_key_here"
    }
}

Isso permite:

Consultas de coleção: "Mostrar minha coleção" em vez de especificar seu nome de usuário
Consultas de usuário: "Mostrar meu perfil do BGG"
Assistência da IA: A IA pode usar automaticamente seu nome de usuário para comparações e análises

Nota: Quando você usa autorreferências (meu, minha, eu) sem definir o BGG_USERNAME, receberá uma mensagem de erro clara.