lichess-mcp

An MCP server that puts the Lichess public API in front of any MCP-compatible agent, so you can ask about chess in plain language instead of reading JSON.

"How did Magnus do in blitz this week, and what did the engine think of his last loss?"

No API key, no account, no OAuth — every tool here uses Lichess' public endpoints.

What you get

Plus a resource, lichess://api-reference, summarising the endpoints behind each tool, the rate limits, and the known gaps — so an agent can read the manual instead of guessing.

Output is shaped for reading, not parsing

Raw Lichess payloads bury the result of a game under ninety clock timestamps. Every tool here returns a small dict with obvious keys:

// get_recent_games("DrNykterstein", count=1, format="blitz")
{
  "game_id": "kAdOQKeh",
  "url": "https://lichess.org/kAdOQKeh",
  "played_at": "2026-04-08T19:39:03+00:00",
  "format": "blitz",
  "time_control": "3+0",
  "opening": "Alekhine Defense: Sämisch Attack",
  "color": "black",
  "result": "win",
  "my_rating": 3145,
  "rating_change": 8,
  "my_accuracy": 93,
  "opponent": { "username": "respects_55", "rating": 2644, "accuracy": 89 },
  "pgn": "[Event \"Take Take Take Arena\"]\n..."
}

Engine lines come back as SAN, because 1... e5 2. g3 Nf6 is legible and e7e5 g2g3 g8f6 is not. Evaluations are normalised so a positive score always favours the side to move, and forced mates are reported as mate_in rather than a huge centipawn number.

Related MCP server: Chess.com MCP Server

Install

Requires Python 3.10+.

uvx lichess-mcp

or

pip install lichess-mcp

Claude Desktop

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "lichess": {
      "command": "uvx",
      "args": ["lichess-mcp"]
    }
  }
}

If you installed with pip rather than using uvx, point at the installed script instead:

{
  "mcpServers": {
    "lichess": {
      "command": "lichess-mcp"
    }
  }
}

Claude Code

claude mcp add lichess -- uvx lichess-mcp

Try these

1. "What's DrNykterstein's blitz rating, and is he on a streak right now?" → get_user_profile

2. "Show me my last 5 rapid games as Black and tell me which openings went badly." → get_recent_games, then get_opening_stats

3. "Pull up today's Lichess puzzle and give me the position — don't tell me the answer yet." → get_puzzle_of_day

4. "Here's a FEN from my game — r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3. What does the engine want to play?" → analyze_position

5. "Find every blunder in lichess.org/dmvL2duu and explain what each one missed." → get_game_analysis

Openings, tournaments and player search work the same way: "How do I score with the Sicilian as White over my last 200 games?", "Who won tournament W1OrjDLM?", "There's a player called something like 'penguin' — find them."

Configuration

Everything is optional.

Being a good API citizen

Lichess is free, donation-funded, and asks clients for at most one request per second. This server enforces that globally with an async rate limiter rather than trusting each tool to behave, and backs off politely on HTTP 429. That means tools which scan many games (get_opening_stats with a large max_games) are deliberately unhurried.

If you want the whole games database, take it from database.lichess.org, not from this server.

Known limits

• Computer analysis is opt-in on Lichess. get_game_analysis and the accuracy fields only have data for games where a player requested analysis. Games without it return analysis_available: false and say so, rather than failing.

• analyze_position reads a cache, not a live engine. Lichess' cloud eval covers positions someone has already analysed — common openings and popular games. Novel positions return cached: false with an explanation.

• get_opening_stats samples recent games. Lichess' personal opening explorer now requires OAuth, so this aggregates the games export instead. Results describe the last max_games games (default 200, max 500), not a lifetime total.

• Streaks are derived, not fetched — Lichess has no streak endpoint, so get_user_profile computes the current run from the 30 most recent rated games.

Development

git clone https://github.com/Anay704/lichess-mcp
cd lichess-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                             # offline, sub-second
.venv/bin/ruff check .

The suite stubs the HTTP layer, so the default run is fast and works offline. A handful of tests that really call lichess.org are opt-in:

LICHESS_MCP_LIVE_TESTS=1 .venv/bin/pytest

License

MIT — see LICENSE.

Not affiliated with or endorsed by Lichess. Lichess is a free/libre, open-source chess server; if you get value out of this, consider donating to them.