Lichess MCP

Interaja com a plataforma de xadrez Lichess usando linguagem natural.

GitHub
17

Documentação

Lichess MCP

smithery badge

Fale com o Lichess em linguagem natural para interagir com a plataforma de xadrez. Use com o Claude Desktop para jogar partidas, analisar posições e gerenciar suas atividades de xadrez.

Construído usando o Model Context Protocol.

Lichess MCP server

O servidor permite:

  • Gerenciar sua conta no Lichess
  • Jogar partidas de xadrez e desafios
  • Analisar posições e partidas
  • Participar de torneios e equipes
  • Interagir com outros jogadores

Configuração

O token da API do Lichess pode ser definido de duas maneiras:

  1. Variáveis de ambiente: Adicione ao arquivo .env na raiz do projeto ou defina diretamente:

    LICHESS_TOKEN=your-lichess-api-token

  2. Usando a ferramenta set_token durante a execução:

    set_token({
  token: "your-lichess-api-token"
});

O token pode ser gerado em https://lichess.org/account/oauth/token

Ferramentas Disponíveis

1. Gerenciamento de Conta

// Set your Lichess API token
set_token({
  token: "your-lichess-api-token"
});

// Get your Lichess profile
get_my_profile();

// Get another user's profile
get_user_profile({
  username: "player_name",
  trophies: true  // include trophies, optional
});

2. Jogo de Partidas

// Create a challenge against another player
create_challenge({
  username: "opponent_username",
  timeControl: "10+0",  // 10 minutes, no increment
  color: "random"       // or "white", "black"
});

// Make a move in a game
make_move({
  gameId: "abcd1234",
  move: "e2e4",
  offeringDraw: false
});

// Get your ongoing games
get_ongoing_games({
  nb: 10  // number of games to fetch
});

3. Análise de Partidas

// Export a game in PGN format
export_game({
  gameId: "abcd1234",
  clocks: true,
  evals: true
});

// Get cloud evaluation for a position
get_cloud_eval({
  fen: "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2"
});

4. Torneios

// List current tournaments
get_arena_tournaments();

// Join a tournament
join_arena({
  tournamentId: "abc123"
});

// Create a new tournament
create_arena({
  name: "My Tournament",
  clockTime: 3,
  clockIncrement: 2,
  minutes: 45
});

5. Interfaces Interativas (Claude Desktop)

Estas ferramentas abrem um tabuleiro de xadrez real dentro do chat — arraste peças, navegue pelos lances e clique nas árvores de abertura — usando a extensão MCP Apps. Em clientes sem suporte a interface, cada ferramenta retorna uma resposta em texto contendo links FEN/PGN/Lichess.

// Open today's daily puzzle (or a specific id) as an interactive solver.
play_puzzle({ puzzleId: "Bmfot" });

// Step through a Lichess game or raw PGN with prev/next/play controls.
view_pgn({ gameId: "abcd1234" });
view_pgn({ pgn: "1. e4 e5 2. Nf3 ..." });

// Walk the opening tree: click moves to drill down; toggle masters/lichess.
explore_openings({ source: "masters" });

Notação de Xadrez

Formatos de Lance

A API do Lichess aceita lances nos seguintes formatos:

  • UCI: Formato Universal de Interface de Xadrez (ex.: e2e4, g8f6)
  • SAN: Notação Algébrica Padrão (ex.: e4, Nf6) - apenas para alguns endpoints

Formato FEN

A Notação Forsyth-Edwards (FEN) é usada para representar posições de xadrez:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

Isso representa:

  • Posições das peças (da 8ª fileira à 1ª fileira)
  • Cor ativa (b/p)
  • Disponibilidade de roque (KQkq)
  • Casa alvo de en passant
  • Contador de meio-lances
  • Número do lance completo

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

  • Lances ou posições inválidos
  • Problemas de autenticação
  • Limites de taxa
  • Casos de recurso não encontrado

Instruções de Configuração

Instalação via Smithery

Para instalar a Integração Lichess para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @karayaman/lichess-mcp --client claude

Instalação Manual

  1. Clone o repositório:

    git clone https://github.com/karayaman/lichess-mcp.git
cd lichess-mcp

  2. Instale as dependências:

    npm install

  3. Configure as variáveis de ambiente: Crie um arquivo .env no diretório raiz:

    LICHESS_TOKEN=your-lichess-api-token

  4. Compile o projeto:

    npm run build

  5. Instale o pacote globalmente (recomendado para integração com Claude Desktop):

    npm install -g

  6. Inicie o servidor (para uso autônomo):

    npm start

Configurando o Claude Desktop

Para usar este servidor MCP com o Claude Desktop:

  1. Localize o arquivo de configuração do Claude Desktop:

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

  2. Adicione o servidor Lichess MCP à sua configuração:

    {
  "mcpServers": {
    "lichess": {
      "command": "lichess-mcp",
      "env": {
        "LICHESS_TOKEN": "your-lichess-api-token",
        "DEBUG": "*"
      }
    }
  }
}

    Observação: Substitua your-lichess-api-token pelo seu token real da API do Lichess. A variável de ambiente DEBUG é opcional, mas útil para solução de problemas.

  3. (Opcional) Você também pode adicionar outros servidores MCP:

    {
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    },
    "lichess": {
      "command": "lichess-mcp",
      "env": {
        "LICHESS_TOKEN": "your-lichess-api-token"
      }
    }
  }
}

  4. Reinicie o Claude Desktop para aplicar as alterações.

    • Certifique-se de fechar completamente o Claude Desktop (incluindo pela bandeja do sistema/barra de menus)
    • Abra o Claude Desktop novamente
    • Procure por um ícone de martelo na interface, que indica que os servidores MCP estão conectados

  5. Teste a integração perguntando ao Claude sobre sua conta no Lichess:

    • "Mostre meu perfil no Lichess"
    • "Inicie uma nova partida de xadrez com controle de tempo de 10 minutos"

Solução de Problemas

Se você encontrar problemas com a conexão do servidor MCP:

  1. Certifique-se de que instalou o pacote globalmente com npm install -g
  2. Verifique se o comando lichess-mcp está disponível no seu PATH (which lichess-mcp)
  3. Verifique se o arquivo de configuração tem o formato correto (o formato mais recente mcpServers em vez de mcp_servers)
  4. Reinicie o Claude Desktop completamente
  5. Tente ativar o Modo Desenvolvedor no Claude Desktop (se disponível) para registro adicional
  6. Verifique se o token da API do Lichess é válido

Referências