home / mcp / chess mcp server

Chess MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ibuildthecloud-chess-mcp": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

You can run an interactive chess game experience that exposes chess actions as MCP tools and provides a web-based chessboard UI. This MCP server lets you play, manage game state across sessions, and interact with chess functionality through MCP clients or a browser UI.

How to use

You will connect to the MCP endpoint to access chess tools and the interactive UI. Use the chess_get_board_state tool to retrieve the current board and valid moves, and the chess_move tool to play moves or start a new game. The server preserves your game state per session, so you can disconnect and reconnect with the same session to resume the game.

How to install

Follow these steps to set up the Chess MCP Server on your machine.

# Prerequisites
Node.js 18+
npm

# 1) Install dependencies
npm install

# 2) Run the development server
npm run dev

Configuration and usage notes

Key features include a full chess implementation with move validation, session-based game persistence, and a web-based interactive chessboard. The MCP tools expose core actions such as getting the board state and making moves. Game state is stored as FEN strings in the file system under a persistent games directory and resumes when you reconnect with the same session.

Troubleshooting and tips

If you do not see the MCP endpoint at http://localhost:3000/mcp ensure the development server is running and that there are no port conflicts. Check terminal output for binding messages and any errors related to dependencies. Verify that the games directory is writable if you experience persistence issues.

Project structure overview

The server is organized with a main server file that wires MCP tools and UI, a store module for saving game state, and a MCP framework for middleware integration. A games directory holds persistent game files using FEN notation.

Available tools and how they work

The server exposes a set of MCP tools for chess gameplay. Two primary tools are chess_get_board_state and chess_move. chess_get_board_state returns the current board with a visual representation and valid moves. chess_move accepts standard algebraic notation to perform a move or start a new game when the move value is new.

Security and environment considerations

Run the server in a trusted environment. The server persists game state locally; ensure the hosting directory has appropriate permissions to prevent unauthorized access to FEN strings and session data.

Notes on persistence and session handling

Each game is associated with a session ID. If you reconnect using the same session, the server resumes the corresponding game state from the saved FEN notation.

Available tools

chess_get_board_state

Get the current state of the chess board with a visual representation and valid moves.

chess_move

Make a move in standard algebraic notation or start a new game; supports all legal moves and updates the persistent session state.