Lichess MCP

用自然语言与Lichess交流，以互动方式使用这个国际象棋平台。通过Claude Desktop可以进行游戏、分析局面以及管理你的国际象棋活动。

该项目基于Model Context Protocol构建。

该服务器支持：

• 管理您的Lichess账户
• 进行国际象棋对局和挑战
• 分析局面和对局
• 加入锦标赛和团队
• 与其他玩家互动

配置

可以通过两种方式设置Lichess API令牌：

1. 环境变量：在项目根目录下的.env文件中添加它或直接设置：

   LICHESS_TOKEN=your-lichess-api-token
   

2. 在运行时使用set_token工具：

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

可以在https://lichess.org/account/oauth/token生成令牌。

可用工具

1. 账户管理

// 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. 对局

// 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. 对局分析

// 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. 锦标赛

// 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
});

国际象棋记谱法

行棋格式

Lichess API接受以下格式的行棋：

• UCI：通用国际象棋接口格式（例如，e2e4, g8f6）
• SAN：标准代数记谱法（例如，e4, Nf6）- 仅适用于某些端点

FEN 格式

Forsyth-Edwards Notation (FEN) 用于表示国际象棋局面：

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

这表示：

• 棋子位置（从第8行到第1行）
• 当前行动方颜色（白/黑）
• 堡垒权可用性（KQkq）
• 过路兵目标格
• 半步计时器
• 完整步数

错误处理

服务器提供详细的错误信息，包括：

• 无效的走法或局面
• 认证问题
• 速率限制
• 资源未找到的情况

设置说明

1. 克隆仓库：

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

2. 安装依赖项：

   npm install
   

3. 配置环境变量：
   在根目录下创建一个.env文件：

   LICHESS_TOKEN=your-lichess-api-token
   

4. 构建项目：

   npm run build
   

5. 全局安装包（推荐用于Claude Desktop集成）:

   npm install -g
   

6. 启动服务器（独立使用）:

   npm start
   

配置 Claude Desktop

要将此MCP服务器与Claude Desktop一起使用：

1. 找到你的 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. 将 Lichess MCP 服务器添加到你的配置中：

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

   注意：将 your-lichess-api-token 替换为你的实际 Lichess API 令牌。DEBUG 环境变量是可选的，但有助于故障排除。

3. （可选）你也可以添加其他 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. 重启 Claude Desktop 以应用更改。

   • 确保完全关闭 Claude Desktop（包括从系统托盘/菜单栏）
   • 再次启动 Claude Desktop
   • 在界面中查找锤子图标，这表示 MCP 服务器已连接

5. 通过询问 Claude 有关你的 Lichess 账户的信息来测试集成：

   • “显示我的 Lichess 个人资料”
   • “开始一个新的 10 分钟时间控制的棋局”

故障排除

如果你遇到 MCP 服务器连接问题：

1. 确保你已使用 npm install -g 全局安装了包
2. 验证 lichess-mcp 命令在你的 PATH 中可用（which lichess-mcp）
3. 检查你的配置文件格式是否正确（使用较新的 mcpServers 格式而不是 mcp_servers）
4. 完全重启 Claude Desktop
5. 尝试启用 Claude Desktop 的开发者模式（如果可用）以获取额外的日志
6. 验证你的 Lichess API 令牌是否有效

参考资料

• Model Context Protocol
• Lichess API 文档