# Chess Mcp

> Chess MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-ibuildthecloud-chess-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ibuildthecloud](https://agentstack.voostack.com/s/ibuildthecloud)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ibuildthecloud](https://github.com/ibuildthecloud)
- **Source:** https://github.com/ibuildthecloud/chess-mcp

## Install

```sh
agentstack add mcp-ibuildthecloud-chess-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
npm install
```

### Development

Start the development server:

```bash
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:

```typescript
// 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ibuildthecloud](https://github.com/ibuildthecloud)
- **Source:** [ibuildthecloud/chess-mcp](https://github.com/ibuildthecloud/chess-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ibuildthecloud-chess-mcp
- Seller: https://agentstack.voostack.com/s/ibuildthecloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.