Lichess MCP

使用自然语言与 Lichess 交流，与象棋平台进行互动。可以结合 Claude Desktop 使用，进行游戏、分析棋局和管理象棋活动。

基于 Model Context Protocol 构建。

该服务器支持以下功能：

管理您的 Lichess 账户
进行象棋游戏和挑战
分析棋局和游戏
参加锦标赛和团队
与其他玩家互动

配置

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

环境变量：将其添加到项目根目录的 .env 文件中，或直接设置：
```
LICHESS_TOKEN=your-lichess-api-token
```

在运行时使用 set_token 工具：

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

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

可用工具

1. 账户管理

// 设置您的 Lichess API 令牌
set_token({
  token: "your-lichess-api-token"
});

// 获取您的 Lichess 个人资料
get_my_profile();

// 获取其他用户的个人资料
get_user_profile({
  username: "player_name",
  trophies: true  // 包含奖杯，可选
});

2. 游戏玩法

// 创建对另一个玩家的挑战
create_challenge({
  username: "opponent_username",
  timeControl: "10+0",  // 10 分钟，无加时
  color: "random"       // 或 "white", "black"
});

// 在游戏中移动棋子
make_move({
  gameId: "abcd1234",
  move: "e2e4",
  offeringDraw: false
});

// 获取您正在进行的游戏
get_ongoing_games({
  nb: 10  // 要获取的游戏数量
});

3. 游戏分析

// 以 PGN 格式导出游戏
export_game({
  gameId: "abcd1234",
  clocks: true,
  evals: true
});

// 获取某个位置的云评估
get_cloud_eval({
  fen: "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2"
});

4. 锦标赛

// 列出当前锦标赛
get_arena_tournaments();

// 加入锦标赛
join_arena({
  tournamentId: "abc123"
});

// 创建新锦标赛
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 行）
活动颜色（w/b）
可用的王车易位（KQkq）
过路兵目标方格
半回合时钟
完整回合数

错误处理

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

无效的移动或位置
认证问题
速率限制
资源未找到的情况

安装说明

通过 Smithery 安装

要通过 Smithery 自动安装 Lichess Integration for Claude Desktop：

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

手动安装

克隆仓库：

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

安装依赖：
```
npm install
```
配置环境变量：在根目录创建 .env 文件：
```
LICHESS_TOKEN=your-lichess-api-token
```
构建项目：
```
npm run build
```
全局安装包（推荐用于 Claude Desktop 集成）：
```
npm install -g
```
启动服务器（用于独立使用）：
```
npm start
```

配置 Claude Desktop

要在 Claude Desktop 中使用此 MCP 服务器：

找到您的 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

将 Lichess MCP 服务器添加到您的配置中：

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

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

（可选）您可以添加其他 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"
      }
    }
  }
}

重启 Claude Desktop 以应用更改。
- 确保完全关闭 Claude Desktop（包括从系统托盘/菜单栏中）
- 再次启动 Claude Desktop
- 在界面中查找锤子图标，表示 MCP 服务器已连接
通过询问 Claude 关于您的 Lichess 账户来测试集成：
- "显示我的 Lichess 个人资料"
- "开始一个新的象棋游戏，时间控制为 10 分钟"

故障排除

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

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