How do I use Chess MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Chess MCP Server Start a new chess game against you at level 5. You go first." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

♟️ Chess MCP Server

Give your AI Agent eyes to see the board and hands to make the move.

This is not just a chess API. It's a Model Context Protocol (MCP) server designed to let Large Language Models (LLMs) like Claude play chess agentically.

Capable of visualizing the board in real-time HTML, understanding spatial relationships via Markdown, and challenging you with a hybrid difficulty engine (Levels 1-10)—or simply facilitating a game between you and your Agent.

🚀 Features

MCP-UI Support: Interactive HTML board embedded directly in the chat (where supported).
Hybrid AI Engine: Adjustable difficulty from "Random Blunderer" (Level 1) to "Minimax Master" (Level 10).
Agent vs. Agent: Let two AI personalities battle it out.
Web Dashboard: Automatically launches a local sidecar dashboard (http://localhost:8080) to monitor all active games.

📦 Installation

Prerequisites

Python 3.10+
An MCP Client (e.g., Claude Desktop, Cursor)

1. Installation

You can install directly from PyPI:

pip install chess-mcp-server

2. Configure MCP Client

Add the following to your MCP Client configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Alternatively, using pip installation:

{ "mcpServers": { "chess": { "command": "python", "args": ["-m", "src.mcp_server"] } } }

🛠️ Development

If you want to modify the code:

Clone & Setup
git clone https://github.com/fritzprix/chess-mcp-server.git cd chess-mcp-server python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

🎮 How to Play

Once the server is connected, you can ask your Agent to start a game.

Start a Game

Ask: "Start a new chess game against the computer at level 5."

The Agent calls createGame.
Pro Tip: You can also ask "I want to play against YOU. Create a game where you are White."

The Game Loop

Your Move:
- Interact with the HTML Board if shown. Drag your piece and click Confirm.
- Or tell the Agent: "Move pawn to e4."
Agent's Turn:
- The Agent calls waitForNextTurn.
- It sees the board (Markdown or HTML) and thinks about the move.
- It calls finishTurn to submit its move.
Checkmate:
- If you deliver the final blow, you can check the "Claim Checkmate" box on the UI or tell the Agent "Checkmate!".