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 representation

• chess_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:

Development

Start the development server:

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:

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

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.