karayaman/lichess-mcp

Speak to Lichess in natural language to interact with the chess platform. Use it with Claude Desktop to play games, analyze positions, and manage your chess activities.
Built using the Model Context Protocol.
The server enables:
Managing your Lichess account
Playing chess games and challenges
Analyzing positions and games
Joining tournaments and teams
Interacting with other players
## Lichess Token
Create a token at https://lichess.org/account/oauth/token. Tick only the scopes you need. Some tools act on your account (sending messages, creating challenges, upgrading to a bot account), and the model reads text other Lichess users wrote. The token's scopes limit what a misled model can do.
Ways to give the server your token, most secure first:
1. Recommended: keep it in your OS secret store and pass it in at launch. The token never sits in a plaintext file or in the chat.
macOS (Keychain). Store it once; the command prompts for the token:
bash
security add-generic-password -s lichess-mcp -a "$USER" -w
Then have your MCP client start the server like this:
json
"lichess": {
"command": "/bin/sh",
"args": ["-c", "LICHESSTOKEN=\"$(security find-generic-password -s lichess-mcp -w)\" exec lichess-mcp"]
Linux (libsecret): store it with secret-tool store --label="Lichess MCP" service lichess-mcp and read it with $(secret-tool lookup service lichess-mcp) in the same way. A password manager CLI works too, for example $(op read "op://Private/Lichess/token") with 1Password.
2. The env block of your MCP client's config. Simple, but the token sits in plaintext in that config file. Don't share or commit the file.
json
"lichess": {
"command": "lichess-mcp",
"env": { "LICHESSTOKEN": "your-lichess-api-token" }
3. A .env file containing LICHESSTOKEN=your-lichess-api-token. Also plaintext. The server reads .env from the directory it starts in, and MCP clients often start it somewhere else, so this suits running from a clone with npm start. .env is in .gitignore; keep it private with chmod 600 .env.
4. Not recommended: the settoken tool. The token passes through the conversation, so it's stored in your chat history and sent to the model provider. If you use it for a quick test, use a short-lived token and revoke it afterwards at https://lichess.org/account/oauth/token.
## Available Tools
### 1. Account Management
typescript
// Get your Lichess profile
getmyprofile();
// Get another user's profile
getuserprofile({
username: "playername",
trophies: true // include trophies, optional
});
### 2. Game Play
Needs the challenges and board toolsets (see Toolsets).
typescript
// Create a challenge against another player
createchallenge({
username: "opponentusername",
timeControl: "10+0", // 10 minutes, no increment
color: "random" // or "white", "black"
});
// Make a move in a game
makemove({
gameId: "abcd1234",
move: "e2e4",
offeringDraw: false
});
// Get your ongoing games
getongoinggames({
nb: 10 // number of games to fetch
});
### 3. Game Analysis
typescript
// Export a game in PGN format
exportgame({
gameId: "abcd1234",
clocks: true,
evals: true
});
// Get cloud evaluation for a position
getcloudeval({
fen: "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2"