Chess

You can run and interact with a chess-playing MCP server that combines a Python backend with a React frontend to offer an interactive board, move validation, and AI-assisted analysis. This server lets you play chess in conversation, see a live board, get engine suggestions, and practice puzzles, all within an MCP client.

How to use

Start a game by telling the MCP client to begin with a move, for example: ChessMCP e4 or Let\'s play chess! I\'ll start with e4. The interactive chess board appears and tracks your moves.

Make moves by typing algebraic notation, such as Nf3, e5, Bc4, or Nc6. Supported patterns include simple moves like e4, captures like exd5, castling with O-O or O-O-O, pawn promotions like e8=Q, checks like Qh5+, and checkmates like Qf7#.

Use extra commands to interact with the game state and features. For example, ask for the current status, load a puzzle, request engine analysis, or reset the game when you want to start over.

How to install

Prerequisites you need before starting: Install Python 3.8 or newer, Node.js 18 or newer, and Stockfish if you want engine analysis.

Step 1. Install Python dependencies for the server.

cd server
pip3 install -r requirements.txt

Step 2. Install Stockfish (optional, for analysis). You can install Stockfish with your system package manager.

# macOS
brew install stockfish

# Ubuntu/Debian
sudo apt-get install stockfish

Step 3. Install frontend dependencies for the React component.

pm install

Step 4. Build the frontend component to generate the assets used by the MCP server.

npm run build

Step 5. The MCP server is configured to run via a local JSON config placed at ~/.cursor/mcp.json. Use the following configuration to run the chess MCP server locally.

{
  "mcpServers": {
    "chess": {
      "command": "python3",
      "args": ["/path/to/ChessMCP/server/main.py"],
      "env": {
        "PYTHONPATH": "/path/to/ChessMCP/server"
      }
    }
  }
}

Configuration and usage notes

The server loads its frontend from the built assets, typically assets/chess-board.html, and uses the Python backend for game logic and analysis. Ensure the paths in the config match where you placed the ChessMCP project files.

If you want to run the server in development mode with hot reloading, start the frontend dev server and the Python backend separately as described in the workflow.

Troubleshooting and tips

Widget rendering issues: confirm you built the frontend and that assets/chess-board.html exists, then check the server logs for errors.

If Stockfish cannot be found, update the path used by the server to point to your Stockfish binary.

If you encounter build errors, run a typecheck to surface TypeScript errors, then fix them in the source.

Available tools

chess_move

Input: move string in algebraic notation. Output: updated board state with FEN, move history, and game status. Renders the interactive chess board.

chess_stockfish

Input: depth integer. Output: best move, evaluation, and principal variation. The widget can access this tool for in-board analysis.

chess_reset

Input: none. Output: confirmation and a fresh starting position for a new game.

chess_status

Input: none. Output: current game status, whose turn it is, player names, move count, and recent moves.

chess_puzzle

Input: difficulty level (easy, medium, hard). Output: mate-in-1 puzzle position with a hint; widget displays the puzzle on the board.