Chess MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to play chess against users. The server provides tools for managing chess games, making moves, evaluating positions, and visualizing the board.

Features

• Game Management: Create new games, get board state, visualize positions
• Move Validation: Validate moves before making them
• AI Opponent: Play against Stockfish chess engine
• Position Evaluation: Get engine evaluation of positions
• Move History: Track moves with undo functionality
• Board Visualization: ASCII art board representation

Requirements

• Python 3.11 or higher
• uv package manager
• Stockfish chess engine (included in server/bin/stockfish/)

Installation

1. Clone the repository:

git clone <repository-url>
cd chess-mcp

2. Install dependencies and the package:

uv sync

This will:

• Create a virtual environment
• Install all dependencies (including mcp and chess)
• Install the package in editable mode

Running the Server

Using the Entry Point

After installation, you can run the server using:

uv run chess-mcp

Running as a Module

Alternatively, you can run it as a Python module:

uv run -m server.main

The server runs on stdio transport, which means it communicates via standard input/output. This is the standard way MCP servers interact with clients.

Configuration for MCP Clients

Claude Desktop

To use this server with Claude Desktop, add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chess-game": {
      "command": "uv",
      "args": [
        "run",
        "chess-mcp"
      ],
      "cwd": "/path/to/chess-mcp"
    }
  }
}

Replace /path/to/chess-mcp with the absolute path to this project directory.

Other MCP Clients

For other MCP clients, configure them to run:

uv run chess-mcp

Make sure the working directory is set to the project root.

Available Tools

The server provides the following MCP tools:

Game State

• new_game_tool: Creates a new chess game
• get_state_tool: Returns the current board state in FEN format
• visualize_board_tool: Returns an ASCII art visualization of the board

Moves

• make_move_tool(move: str): Makes a move in UCI format (e.g., "e2e4")
• ai_make_move_tool: Makes a move using the AI opponent
• undo_move_tool: Undoes the last move

Validation

• validate_move_tool(move: str): Validates if a move is legal

Analysis

• evaluate_board_tool: Returns the engine's evaluation of the position in centipawns

Project Structure

appli/
├── server/
│   ├── main.py              # MCP server entry point
│   ├── config.py            # Configuration (paths, etc.)
│   ├── engine/              # Stockfish engine wrapper
│   ├── storage/             # File I/O and serialization
│   └── tools/               # MCP tool implementations
├── storage/                 # Game state storage
│   ├── current_game.fen     # Current board position
│   └── move_history.json    # Move history for undo
├── tests/                   # Test files for tools
├── pyproject.toml           # Project configuration
└── README.md                # This file

Storage

The server stores game state in the storage/ directory:

• current_game.fen: Current board position in FEN notation
• move_history.json: List of moves made (for undo functionality)

Development

Running Tests

Install test dependencies:

uv sync --extra dev

Run tests:

uv run pytest

Run tests with coverage:

uv run pytest --cov=server --cov-report=html

Adding New Tools

1. Create a function in the appropriate server/tools/ module
2. Register it in server/tools/registry.py
3. Add it to the register_tools() function

Troubleshooting

Stockfish Not Found

If you get an error about Stockfish not being found:

• Check that server/bin/stockfish/ contains the appropriate binary for your platform
• The server automatically detects your platform and selects the correct binary
• Supported: macOS (Intel/Apple Silicon), Linux, Windows

Import Errors

If you encounter import errors:

• Make sure you've run uv sync to install the package
• Verify you're in the project root directory
• Check that the virtual environment is activated

Acknowledgments

• Uses python-chess for chess logic
• Uses Stockfish chess engine
• Built with FastMCP for MCP server functionality