Lichess MCP

Lichess MCP

使用自然语言与 Lichess 对话，来操作这个国际象棋平台。将其与 Claude Desktop 搭配使用，可进行对局、分析局面并管理你的国际象棋活动。

使用 Model Context Protocol 构建。

此服务支持：

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

Lichess 令牌

在 https://lichess.org/account/oauth/token 创建令牌。只勾选你需要的权限范围。有些工具会操作你的账户（发送消息、创建挑战、升级为机器人账户），而模型会读取其他 Lichess 用户撰写的文本。令牌的权限范围可以限制被误导的模型所能执行的操作。

以下是向服务提供令牌的方式，按安全性从高到低排列：

1. 建议：将令牌保存在操作系统的密钥存储中，并在启动时传入。 令牌不会存放在明文文件中，也不会出现在聊天中。

   macOS（Keychain）。只需存储一次；命令会提示你输入令牌：

   security add-generic-password -s lichess-mcp -a "$USER" -w
   

   然后让 MCP 客户端按如下方式启动服务：

   "lichess": {
     "command": "/bin/sh",
     "args": ["-c", "LICHESS_TOKEN=\"$(security find-generic-password -s lichess-mcp -w)\" exec lichess-mcp"]
   }
   

   Linux（libsecret）：使用 secret-tool store --label="Lichess MCP" service lichess-mcp 存储令牌，并以相同方式通过 $(secret-tool lookup service lichess-mcp) 读取。也可以使用密码管理器 CLI，例如通过 1Password 使用 $(op read "op://Private/Lichess/token")。

2. MCP 客户端配置中的 env 区块。 这种方式简单，但令牌会以明文形式保存在配置文件中。不要分享或提交该文件。

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

3. 包含 LICHESS_TOKEN=your-lichess-api-token 的 .env 文件。 令牌同样以明文形式保存。服务会从启动目录读取 .env，而 MCP 客户端通常会从其他目录启动服务，因此这种方式适合在克隆仓库后通过 npm start 运行。.env 已列入 .gitignore；请使用 chmod 600 .env 将其设为私有。

4. 不建议：使用 set_token 工具。 令牌会经过对话，因此会保存在聊天记录中，并发送给模型提供商。如果你只是想快速测试，请使用短期令牌，并在测试后前往 https://lichess.org/account/oauth/token 撤销它。

可用工具

1. 账户管理

// Get your Lichess profile
get_my_profile();

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

2. 对局

需要 challenges 和 board 工具集（参见工具集）。

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

需要 arena 工具集（参见工具集）。

// 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. 交互式 UI（Claude Desktop）

这些工具会在聊天中打开真实的棋盘——你可以拖动棋子、浏览 着法，并点击查看开局树——使用的是 MCP Apps 扩展。在不支持 UI 的客户端中，每个工具都会回退为 包含 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" });

工具集

服务器有约 190 个工具。每个已启用工具的描述都会在每次会话开始时发送给模型，因此默认只启用核心工具集：约 70 个工具，大约是完整列表的三分之一。

使用 LICHESS_TOOLSETS 选择工具集，它是一个以逗号分隔的列表：

值	启用内容
(未设置) 或 core	account、users、relations、messaging、games、opening-explorer、tablebase、puzzles、tv、analysis、apps
core,challenges,board	核心工具集，以及挑战玩家和对弈工具
all	所有工具集

其他工具集包括 board、bot、bulk-pairings、engine、challenges、arena、swiss、simuls、teams、studies 和 broadcasts。如果名称不在此列表中，服务器会在启动时停止，并显示有效名称。

设置令牌时一并配置，例如在 MCP 客户端的配置中使用 "env": { "LICHESS_TOOLSETS": "core,arena,swiss" }。

模型还可以在会话中途使用 enable_toolset 工具启用工具集；该工具的描述会逐行列出当前关闭的工具集。这需要客户端在服务器表示工具列表已更改时刷新工具列表；否则，请设置 LICHESS_TOOLSETS 并重启。由于模型可以启用任意工具集，LICHESS_TOOLSETS 只能节省上下文，不能限制模型可以执行的操作。限制由令牌的权限范围决定（参见 Lichess 令牌）。

国际象棋记谱

着法格式

Lichess API 接受以下格式的着法：

• UCI：通用国际象棋接口格式（例如 e2e4、g8f6）
• SAN：标准代数记谱法（例如 e4、Nf6）——仅适用于部分端点

FEN 格式

Forsyth-Edwards 记谱法（FEN）用于表示国际象棋局面：

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

其表示：

• 棋子位置（从第 8 横排到第 1 横排）
• 行棋方（w/b）
• 易位权限（KQkq）
• 吃过路兵目标格
• 半回合计数
• 完整回合数

错误处理

服务器会针对以下情况提供详细的错误消息：

• 着法或局面无效
• 身份验证问题
• 速率限制
• 未找到资源

设置说明

通过 Smithery 安装

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

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

手动安装

1. 克隆代码库：

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

2. 安装依赖项：

   npm install
   

3. 设置令牌：参见 Lichess 令牌。

4. 构建项目：

   npm run build
   

5. 全局安装软件包（推荐用于与 Claude Desktop 集成）：

   npm install -g
   

6. 启动服务器（用于独立运行）：

   npm start
   

配置 Claude Desktop

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

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": "/bin/sh",
         "args": ["-c", "LICHESS_TOKEN=\"$(security find-generic-password -s lichess-mcp -w)\" exec lichess-mcp"]
       }
     }
   }
   

   此配置会从 macOS Keychain 读取令牌（有关如何存储令牌和其他选项，请参见 Lichess 令牌）。如需排查问题，请添加 "env": { "DEBUG": "*" }。

3.（可选）你还可以添加其他 MCP 服务：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    },
    "lichess": {
      "command": "/bin/sh",
      "args": ["-c", "LICHESS_TOKEN=\"$(security find-generic-password -s lichess-mcp -w)\" exec lichess-mcp"]
    }
  }
}

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 中启用 Developer Mode（如果可用），以获取更多日志
6. 确认 Lichess API 令牌有效

参考资料

• 模型上下文协议
• Lichess API 文档