Lichess MCP

Lichess MCP

自然な言葉で Lichess に話しかけて、チェスプラットフォームを操作できます。Claude Desktop と一緒に使えば、対局したり、局面を分析したり、チェスのアクティビティを管理したりできます。

Model Context Protocol を使用して構築されています。

このサーバーでは、次のことができます。

• Lichess アカウントの管理
• チェスの対局やチャレンジ
• 局面や対局の分析
• トーナメントやチームへの参加
• 他のプレイヤーとの交流

Lichess トークン

https://lichess.org/account/oauth/token でトークンを作成してください。必要なスコープだけにチェックを入れてください。一部のツールはアカウントに対する操作（メッセージの送信、チャレンジの作成、ボットアカウントへのアップグレード）を行い、モデルは他の Lichess ユーザーが書いたテキストを読み取ります。トークンのスコープによって、誤った判断をしたモデルができることを制限できます。

サーバーにトークンを渡す方法を、安全性の高い順に示します。

1. 推奨：OS のシークレットストアに保存し、起動時に渡します。 トークンが平文ファイルやチャットに保存されることはありません。

   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) で読み取ります。1Password の $(op read "op://Private/Lichess/token") など、パスワードマネージャーの CLI も使えます。

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 個です。これは全リストの約 3 分の 1 にあたります。

カンマ区切りのリスト LICHESS_TOOLSETS でツールセットを選択します。

値	有効になるもの
(未設定) または core	account、users、relations、messaging、games、opening-explorer、tablebase、puzzles、tv、analysis、apps
core,challenges,board	core に、プレイヤーへのチャレンジと対局のプレイを追加
all	すべてのツールセット

その他のツールセットは board、bot、bulk-pairings、engine、challenges、arena、swiss、simuls、teams、studies、broadcasts です。このリストにない名前を指定すると、有効な名前が表示されてサーバーの起動が停止します。

トークンと一緒に設定します。たとえば、MCP クライアントの設定で "env": { "LICHESS_TOOLSETS": "core,arena,swiss" } と指定します。

モデルは enable_toolset ツールを使って、セッションの途中でツールセットを有効にすることもできます。このツールの説明には、無効になっているツールセットが 1 行ずつ記載されています。サーバーから変更の通知があった際にツールリストを更新するクライアントが必要です。そうでない場合は、LICHESS_TOOLSETS を設定して再起動してください。モデルは任意のツールセットを有効にできるため、LICHESS_TOOLSETS はコンテキストを節約しますが、モデルの操作を制限するものではありません。操作を制限するのはトークンのスコープです（Lichess Token を参照）。

チェス表記法

指し手の形式

Lichess API は、次の形式で指し手を受け付けます。

• UCI：Universal Chess Interface 形式（例：e2e4、g8f6）
• SAN：Standard Algebraic Notation（例：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 経由でインストールする

Lichess Integration for Claude Desktop を Smithery 経由で自動的にインストールするには：

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

   これにより、トークンが macOS キーチェーンから読み込まれます（トークンの保存方法とその他の設定については、Lichess Token を参照してください）。問題の調査には、"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. Lichess アカウントについて Claude に質問して、連携をテストします。

   • 「Lichess のプロフィールを表示して」
   • 「10 分の持ち時間で新しいチェスの対局を始めて」

トラブルシューティング

MCP サーバーへの接続で問題が発生した場合は、次の点を確認してください。

1. npm install -g でパッケージをグローバルにインストールしたことを確認します。
2. lichess-mcp コマンドが PATH で利用可能であることを確認します（which lichess-mcp）。
3. 設定ファイルの形式が正しいことを確認します（mcp_servers ではなく、新しい mcpServers 形式を使用します）。
4. Claude Desktop を完全に再起動します。
5. 追加のログを取得するため、Claude Desktop で開発者モードを有効にしてみます（利用可能な場合）。
6. Lichess API トークンが有効であることを確認します。

参考資料

• Model Context Protocol
• Lichess API Documentation