Chess MCP
Chess MCP Server
Installation
npx chess-mcpAsk AI about Chess MCP
Powered by Claude ยท Grounded in docs
I know everything about Chess MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Chess MCP Server
A Model Context Protocol (MCP) server that provides an interactive chess game experience using MCP-UI. This server exposes chess game functionality through MCP tools and provides a web-based chessboard interface for playing games.
Features
- โ๏ธ Full Chess Game: Complete chess implementation using chess.js
- ๐ง MCP Tools: Chess game actions exposed as MCP tools
- ๐ฎ Interactive UI: Web-based chessboard using ChessBoard.js
- ๐พ Game State Management: Persistent game state with session-based saves
Workshop
In the ./workshop directory, you can find a step by step to creating this MCP server.
Architecture
This MCP server is built using Express.js with integrated MCP capabilities:
Key Components
- MCP Server (
src/server.ts): Main server with chess tools and UI generation - Store (
src/lib/store.ts): Game state persistence using file system - MCP Framework (
src/lib/mcp/): Custom MCP middleware implementation with Express integration
MCP Tools Available
chess_get_board_state: Get the current state of the chess board with visual representationchess_move: Make a move in standard algebraic notation (e.g., e4, Nf3, O-O) or start a new game
Getting Started
Prerequisites
- Node.js 18+
- npm
Installation
Install the dependencies:
npm install
Development
Start the development server:
npm run dev
The server will be available at:
- MCP endpoint:
http://localhost:3000/mcp
Development Commands
npm run dev- Start development server
Usage
As an MCP Server
The server exposes MCP tools that can be consumed by MCP clients:
// Get current board state
{
"method": "tools/call",
"params": {
"name": "chess_get_board_state",
"arguments": {}
}
}
// Make a move
{
"method": "tools/call",
"params": {
"name": "chess_move",
"arguments": {
"move": "e4"
}
}
}
// Start a new game
{
"method": "tools/call",
"params": {
"name": "chess_move",
"arguments": {
"move": "new"
}
}
}
Interactive Chessboard
When using the MCP tools, each response includes:
- Text representation: ASCII board and FEN notation with valid moves
- Interactive UI: Drag-and-drop chessboard that allows moves via mouse interaction
Game Rules
- Standard chess rules apply
- Uses chess.js for move validation and game logic
- Supports all legal chess moves including castling, en passant, and pawn promotion
- Game state persists per session ID
Project Structure
src/
โโโ lib/
โ โโโ mcp/ # Custom MCP middleware framework
โ โ โโโ index.ts # Main exports
โ โ โโโ middleware.ts # Express middleware integration
โ โ โโโ header.ts # HTTP header utilities
โ โ โโโ uuid.ts # UUID validation
โ โโโ store.ts # Game state persistence
โโโ server.ts # Main server with chess tools and UI
games/ # Persistent game files (FEN notation)
Game State Persistence
- Each chess game is saved to a JSON file in the
games/directory - Games are identified by MCP session ID
- Game state is stored as FEN (Forsyth-Edwards Notation) strings
- Games automatically resume when reconnecting with the same session
Dependencies
- chess.js: Chess game logic and move validation
- @chrisoakman/chessboardjs: Interactive chessboard UI
- @mcp-ui/server: MCP UI resource creation
- @modelcontextprotocol/sdk: MCP server implementation
- express: Web server framework
License
Apache 2.0 License - see LICENSE file for details.
