Lichess MCP

Interactúa con la plataforma de ajedrez Lichess usando lenguaje natural.

GitHub
17

Documentación

Lichess MCP

smithery badge

Habla con Lichess en lenguaje natural para interactuar con la plataforma de ajedrez. Úsalo con Claude Desktop para jugar partidas, analizar posiciones y gestionar tus actividades de ajedrez.

Construido usando el Protocolo de Contexto de Modelo.

Lichess MCP server

El servidor permite:

  • Gestionar tu cuenta de Lichess
  • Jugar partidas de ajedrez y desafíos
  • Analizar posiciones y partidas
  • Unirte a torneos y equipos
  • Interactuar con otros jugadores

Configuración

El token de la API de Lichess se puede configurar de dos maneras:

  1. Variables de entorno: Añádelo a tu archivo .env en la raíz del proyecto o configúralo directamente:

    LICHESS_TOKEN=your-lichess-api-token

  2. Usando la herramienta set_token durante la ejecución:

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

El token se puede generar en https://lichess.org/account/oauth/token

Herramientas Disponibles

1. Gestión de Cuenta

// 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. Juego 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álisis 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. Torneos

// 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 Interactivas (Claude Desktop)

Estas herramientas abren un tablero de ajedrez real dentro del chat — arrastra piezas, navega movimientos y haz clic en árboles de aperturas — usando la extensión MCP Apps. En clientes sin soporte de interfaz, cada herramienta recurre a una respuesta de texto que contiene enlaces 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" });

Notación de Ajedrez

Formatos de Movimiento

La API de Lichess acepta movimientos en estos formatos:

  • UCI: Formato de Interfaz Universal de Ajedrez (p. ej., e2e4, g8f6)
  • SAN: Notación Algebraica Estándar (p. ej., e4, Nf6) - solo para algunos endpoints

Formato FEN

La Notación Forsyth-Edwards (FEN) se utiliza para representar posiciones de ajedrez:

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

Esto representa:

  • Posiciones de las piezas (de la 8.ª fila a la 1.ª fila)
  • Color activo (b/n)
  • Disponibilidad de enroque (KQkq)
  • Casilla objetivo de captura al paso
  • Reloj de medio movimiento
  • Número de movimiento completo

Manejo de Errores

El servidor proporciona mensajes de error detallados para:

  • Movimientos o posiciones inválidos
  • Problemas de autenticación
  • Límites de velocidad
  • Casos de recurso no encontrado

Instrucciones de Configuración

Instalación mediante Smithery

Para instalar Lichess Integration para Claude Desktop automáticamente mediante Smithery:

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

Instalación Manual

  1. Clona el repositorio:

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

  2. Instala las dependencias:

    npm install

  3. Configura las variables de entorno: Crea un archivo .env en el directorio raíz:

    LICHESS_TOKEN=your-lichess-api-token

  4. Compila el proyecto:

    npm run build

  5. Instala el paquete globalmente (recomendado para la integración con Claude Desktop):

    npm install -g

  6. Inicia el servidor (para uso independiente):

    npm start

Configuración de Claude Desktop

Para usar este servidor MCP con Claude Desktop:

  1. Localiza tu archivo de configuración de 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. Añade el servidor MCP de Lichess a tu configuración:

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

    Nota: Reemplaza your-lichess-api-token con tu token real de la API de Lichess. La variable de entorno DEBUG es opcional pero útil para solucionar problemas.

  3. (Opcional) También puedes añadir otros 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. Reinicia Claude Desktop para aplicar los cambios.

    • Asegúrate de cerrar completamente Claude Desktop (incluyendo desde la bandeja del sistema/barra de menú)
    • Inicia Claude Desktop nuevamente
    • Busca un ícono de martillo en la interfaz, que indica que los servidores MCP están conectados

  5. Prueba la integración preguntando a Claude sobre tu cuenta de Lichess:

    • "Muéstrame mi perfil de Lichess"
    • "Inicia una nueva partida de ajedrez con control de tiempo de 10 minutos"

Solución de Problemas

Si encuentras problemas con la conexión del servidor MCP:

  1. Asegúrate de haber instalado el paquete globalmente con npm install -g
  2. Verifica que el comando lichess-mcp esté disponible en tu PATH (which lichess-mcp)
  3. Comprueba que tu archivo de configuración tenga el formato correcto (el formato más nuevo mcpServers en lugar de mcp_servers)
  4. Reinicia Claude Desktop por completo
  5. Intenta habilitar el Modo Desarrollador en Claude Desktop (si está disponible) para obtener registros adicionales
  6. Verifica que tu token de la API de Lichess sea válido

Referencias