Lichess Connectivity Module

Engage with the Lichess chess servers conversationally to manage your presence, compete, scrutinize game positions, and participate in scheduled tournaments. Designed for use with Claude Desktop for fluid command execution.

Leverages the Model Context Protocol.

This server instance permits the following operations:

• Administrative control over your Lichess membership details
• Initiating and participating in chess contests and specific challenges
• In-depth positional and post-game analysis
• Enrollment in organized competitive ladders and team affiliations
• Communication features directed toward other platform participants

Configuration Directives

The authorization credential (API token) for Lichess can be supplied via two primary avenues:

1. Environment Variables: Place the credential in your project's .env file, or set it directly in your shell environment:

bash LICHESS_TOKEN=your-lichess-api-token

1. Runtime Tool Invocation: Utilize the dedicated configuration function during active operation:

typescript set_token({ token: "your-lichess-api-token" });

The requisite token can be generated by accessing https://lichess.org/account/oauth/token.

Accessible Functionality (Tools)

1. Profile Administration

typescript // Store your Lichess access key set_token({ token: "your-lichess-api-token" });

// Retrieve your personal Lichess statistics get_my_profile();

// Fetch data for a specific external participant get_user_profile({ username: "player_name", trophies: true // Boolean flag to include award data (optional) });

2. Match Execution

typescript // Propose a new game against another user create_challenge({ username: "opponent_username", timeControl: "10+0", // Duration: Ten minutes per side, zero seconds added per move color: "random" // Selection: 'random', 'white', or 'black' });

// Submit a move within an active engagement make_move({ gameId: "abcd1234", move: "e2e4", offeringDraw: false });

// Query the list of currently active games you are involved in get_ongoing_games({ nb: 10 // Maximum number of concurrent games to retrieve });

3. Positional Assessment

typescript // Output a game's notation record in PGN format export_game({ gameId: "abcd1234", clocks: true, evals: true });

// Request computational evaluation for a specified board state get_cloud_eval({ fen: "rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2" });

4. Competitive Events (Tournaments)

typescript // List tournaments currently in progress get_arena_tournaments();

// Register for a specific competitive bracket join_arena({ tournamentId: "abc123" });

// Establish a new competitive event create_arena({ name: "My Tournament", clockTime: 3, clockIncrement: 2, minutes: 45 });

Chess Notation Standards

Move Representation Schemes

The Lichess API endpoint accepts input in these primary formats:

• UCI: Unified Chess Interface notation (e.g., e2e4, g8f6)
• SAN: Standard Algebraic Notation (e.g., e4, Nf6) - applicability is endpoint-dependent

FEN Format Specification

The Forsyth-Edwards Notation (FEN) serves as the standardized string for describing a static arrangement of pieces on the board:

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

This notation encodes:

• Piece placement (detailed rank-by-rank, starting from rank 8 down to rank 1)
• Who's turn it is to move (w for white, b for black)
• Available castling rights (KQkq)
• The square eligible for en passant capture, if any
• Halfmove clock (for the fifty-move rule)
• The current full move number

Error Management

The integration server furnishes granular error reports concerning:

• Input validation failures (illegal moves or positions)
• Authorization failures (token related problems)
• Request throttling violations (API rate limits)
• Requests targeting non-existent resources

Deployment Instructions

Method A: Smithery Integration

To deploy the Lichess Utility for Claude Desktop automatically via Smithery:

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

Method B: Manual Setup

1. Clone Repository:

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

1. Install Dependencies:

bash npm install

1. Configure Environment Variables: Create a file named .env in the root folder:

bash LICHESS_TOKEN=your-lichess-api-token

1. Compile Project Assets:

bash npm run build

1. Global Package Installation (Recommended for Desktop Use): bash npm install -g

2. Start Server (For Standalone Operation): bash npm start

Configuring Claude Desktop Environment

To establish connectivity between Claude Desktop and this MCP server:

1. Locate Configuration File: Find your platform-specific configuration file:

2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Linux: ~/.config/Claude/claude_desktop_config.json

5. Inject Lichess MCP Server Entry: Add the server definition under the mcpServers section:

{ "mcpServers": { "lichess": { "command": "lichess-mcp", "env": { "LICHESS_TOKEN": "your-lichess-api-token", "DEBUG": "*" // Optional: for detailed logging } } } }

Note: Ensure the placeholder token is replaced with your actual Lichess access key.

1. Inclusion of Other Servers (Example): You may combine this with other integrations:

{ "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" } } } }

1. Application Restart: Fully close and relaunch Claude Desktop to initialize the new configuration.

2. Ensure the application is quit completely (check system tray/menu bar).

3. Open Claude Desktop again.

4. Successful connection is often indicated by a wrench or tool icon within the UI.

5. Verification Test: Confirm functionality by issuing a command to Claude, such as:

6. "Display my Lichess profile summary."
7. "Initiate a rapid game with a 15|10 time control."

Troubleshooting Connectivity

If the MCP server fails to link up:

1. Confirm the package was installed globally using npm install -g.
2. Verify that the executable lichess-mcp is discoverable in your system's PATH (which lichess-mcp).
3. Double-check that the configuration file uses the contemporary mcpServers structure (avoiding deprecated naming conventions).
4. Execute a full shutdown and restart of Claude Desktop.
5. If available, activate Developer Mode in Claude Desktop for access to advanced diagnostic logs.
6. Validate the integrity and current validity of your Lichess API access credential.

Resource Links

• Model Context Protocol Specification
• Official Lichess API Documentation

---

WIKIPEDIA Contextual Note: Business enhancement platforms encompass all methodologies, calculations, applications, and control mechanisms utilized by enterprises to navigate market shifts, sustain competitive advantage, and elevate operational results. These systems are classified by function—planning, control, data handling, etc.—and have evolved significantly due to technological acceleration, necessitating strategic selection and customization rather than simple adoption of the newest releases.