The Lichess MCP server allows users to interact with the Lichess chess platform programmatically through natural language. You can:
Account Management: Manage your profile, email, preferences, kid mode settings, API tokens, view timeline, and handle user statistics
Game Play: Create challenges, make moves, manage ongoing games, abort, resign, chat, and handle draws
Game Analysis: Export games in PGN/JSON formats, get cloud evaluations, and analyze positions
Tournaments: Join, create, withdraw, and manage arena and Swiss tournaments
Social Interaction: Follow, block, message, and manage relationships with other players
Team Management: Join, leave, manage teams, and handle join requests
Other Features: Access puzzles, broadcasts, Lichess TV, studies, simultaneous exhibitions (simuls), and FIDE player information
Provides support for loading environment variables from a .env file for configuring the Lichess API token.
Enables comprehensive interaction with the Lichess chess platform, including account management, playing chess games, creating challenges, analyzing positions, managing tournaments, joining teams, and connecting with other players.
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
Configuration
The Lichess API token can be set in two ways:
Environment variables: Add it to your
.env
file in the project root or set it directly:LICHESS_TOKEN=your-lichess-api-tokenUsing the
set_token
tool during runtime:set_token({ token: "your-lichess-api-token" });
The token can be generated at https://lichess.org/account/oauth/token
Available Tools
1. Account Management
2. Game Play
3. Game Analysis
4. Tournaments
Chess Notation
Move Formats
The Lichess API accepts moves in these formats:
UCI: Universal Chess Interface format (e.g.,
e2e4
,g8f6
)SAN: Standard Algebraic Notation (e.g.,
e4
,Nf6
) - only for some endpoints
FEN Format
The Forsyth-Edwards Notation (FEN) is used to represent chess positions:
This represents:
Piece positions (from 8th rank to 1st rank)
Active color (w/b)
Castling availability (KQkq)
En passant target square
Halfmove clock
Fullmove number
Error Handling
The server provides detailed error messages for:
Invalid moves or positions
Authentication issues
Rate limits
Resource not found cases
Setup Instructions
Installing via Smithery
To install Lichess Integration for Claude Desktop automatically via Smithery:
Manual Installation
Clone the repository:
git clone https://github.com/karayaman/lichess-mcp.git cd lichess-mcpInstall dependencies:
npm installConfigure environment variables: Create a
.env
file in the root directory:LICHESS_TOKEN=your-lichess-api-tokenBuild the project:
npm run buildInstall the package globally (recommended for Claude Desktop integration):
npm install -gStart the server (for standalone usage):
npm start
Configuring Claude Desktop
To use this MCP server with Claude Desktop:
Locate your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
Add the Lichess MCP server to your configuration:
{ "mcpServers": { "lichess": { "command": "lichess-mcp", "env": { "LICHESS_TOKEN": "your-lichess-api-token", "DEBUG": "*" } } } }Note: Replace
your-lichess-api-token
with your actual Lichess API token. TheDEBUG
environment variable is optional but helpful for troubleshooting.(Optional) You can add other MCP servers as well:
{ "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" } } } }Restart Claude Desktop to apply the changes.
Make sure to completely close Claude Desktop (including from the system tray/menu bar)
Launch Claude Desktop again
Look for a hammer icon in the interface, which indicates that MCP servers are connected
Test the integration by asking Claude about your Lichess account:
"Show me my Lichess profile"
"Start a new chess game with 10 minutes time control"
Troubleshooting
If you encounter issues with the MCP server connection:
Ensure you've installed the package globally with
npm install -g
Verify that the
lichess-mcp
command is available in your PATH (which lichess-mcp
)Check that your configuration file has the correct format (the newer
mcpServers
format instead ofmcp_servers
)Restart Claude Desktop completely
Try enabling Developer Mode in Claude Desktop (if available) for additional logging
Verify your Lichess API token is valid
References
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
An MCP server that enables natural language interaction with the Lichess chess platform, allowing users to play games, analyze positions, manage their account, and participate in tournaments through Claude.
- Configuration
- Available Tools
- Chess Notation
- Error Handling
- Setup Instructions
- Configuring Claude Desktop
- Troubleshooting
- References
Related Resources
Related MCP Servers
- -securityAlicense-qualityAn MCP server that allows accessing and managing ledger files through Claude by providing account listing, balance checking, and transaction register viewing capabilities.Last updated -3GPL 3.0
- -securityFlicense-qualityAn MCP server that allows Claude to interact with local LLMs running in LM Studio, providing access to list models, generate text, and use chat completions through local models.Last updated -10
- -securityFlicense-qualityAn MCP server that enables Claude and other MCP clients to interact with Mattermost workspaces, providing channel management, messaging capabilities, and topic monitoring functionality.Last updated -16
- AsecurityAlicenseAqualityProvides access to Chess.com player data, game records, and public information through standardized MCP interfaces, allowing AI assistants to search and analyze chess information.Last updated -1051MIT License