Chess Agent ♟️

An LLM agent built using Model Context Protocol to play online games

Pre-requisites

• uv installable via brew.
• Claude Desktop
• Create Lichess account
• Create API key.
• Add API key to a .env file in the projects root directory: API_KEY = ************

Note

When creating an API key only the board:play scope is required.

Set up project:

make project-setup

Quick Start

1. Install server in Claude Desktop:

cd chess_agent

uv run mcp install server.py

Tip

The above command updates the MCP config in Claude desktop. Whilst Claude Desktop only supports stdio transport the server can be directly executed with communication via sse transport and HTTP requests. For documentation on how to do this see direct_execution.md.

Note

If you have Claude Desktop open when you run the above command, you will need to restart it for the server to be available.

2. Interact with MCP server with Claude Desktop.

♟️ Agent vs. Stockfish Bot 🤖:

Can you please log into the Chess API and then create a game against an AI. Once the game has been created the opponent will make the first move. Can you use the previous moves and the layout of the board to determine what an optimal next move will be and then make your own move playing continuously back and forth until completion? Please use the UCI chess standard for your moves, e.g., e2e4.

♟️ Agent vs. User 🧑:

1. Ask agent to login and create a game against a user:

Can you please log into the Chess API and then create a game against the user .

2. Once the game has been created and the opponent has connected and made their first move, the agent will make their move.

Once the game has been created the opponent will make the first move. Can you use the previous moves and the layout of the board to determine what an optimal next move will be and then make your own move playing continuously back and forth until completion? Please use the UCI chess standard for your moves, e.g., e2e4.

Warning

Common Issues:

1. ENOENT error when opening Claude Desktop.

• This is due to Claude Desktop facing issues with running the server with a relative path to uv. To fix this, you need to change the command in the claude_desktop_config.json config to an absolute path. You can find the absolute path by running which uv in your terminal.

2. Not having coreutils installed.

• This is required for the realpath command. You will see the following error in Claude logs: realpath: command not found. You can install it using brew install coreutils.

Application Tests

Application tests for the MCP server can be run with the following command:

uv run application_tests/tests.py

Documentation

Documentation for this project can be found in the docs directory. The following documentation is available:

• direct_execution.md: Documentation on how to run the server directly with sse transport and HTTP requests.
• client-server-interaction.md: Documentation on how MCP clients and servers interact with each other and how clients process user queries.

Useful Links

• Model Context Protocol
• Client Development Docs
• Server Development Docs
• FastMCP
• Claude Messages API