playbooks

home / mcp / chessagine mcp server

ChessAgine MCP Server

ChessAgine MCP is a Model Context Protocol server that gives LLMs deep chess awareness by exposing chess board state, Stockfish analysis, Lichess games and popular chess APIs

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "jalpp-chessagine-mcp": {
      "url": "https://your-project.vercel.app/mcp",
      "headers": {
        "ENV": "<ENV>"
      }
    }
  }
}

ChessAgine MCP is a Model Context Protocol server that gives you deep chess awareness by exposing real-time board state, Stockfish analysis, opening databases, Lichess games, and neural engines including Maia2, Leela, and Elite Leela. It also renders individual positions and full PGN games for in-depth visual analysis, enabling your AI agents to reason about positions, evaluate variations, detect themes, explore game databases, and interact directly with chess engines.

How to use

You will connect your MCP client to ChessAgine MCP to access real-time board information, engine analyses, and game databases. Use the available endpoints to request current board states, run engine evaluations (Stockfish, Maia2, Leela variants), fetch openings, retrieve Lichess games, and render PGN sequences for visual analysis. You can ask your agent to compare engine evaluations across different engines, explore opening repertoires, or render specific positions for deeper study.

How to install

Prerequisites you need before installing ChessAgine MCP:

  • Node.js 22+

Recommended installation flow if you want to run the MCP server locally and connect via Claude Desktop.

How to install

# Option A: Deploy a prebuilt MCP file (recommended for Claude Desktop users)
# You would typically download the chessagine-mcp.mcpb file and import it into Claude Desktop

How to install

Option 2: Local development setup (recommended for developers)

# Prerequisites
node --version
npm --version
# Clone the project
git clone https://github.com/jalpp/chessagine-mcp.git
cd chessagine-mcp
# Install dependencies
npm install
# Build the MCP server and UI assets
npm run build

How to install

Configure an MCP client (Claude Desktop) to connect to your local server. Add the following configuration to your Claude Desktop setup file.

{
  "mcpServers": {
    "chessagine_mcp_local": {
      "command": "node",
      "args": ["/absolute/path/to/chessagine-mcp/build/runner/stdio.js"]
    }
  }
}

How to install

On Windows you would mirror the same approach using the Windows path to the stdio.js script.

{
  "mcpServers": {
    "chessagine_mcp_local": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\chessagine-mcp\\build\\runner\\stdio.js"]
    }
  }
}

How to install

If you prefer deploying a ready-made instance, you can deploy your own copy to Vercel. This exposes the MCP endpoint at a project URL.

1. Fork the repository
2. Go to vercel.com/new and import your fork
3. Deploy without environment variables
4. Your MCP server will be available at https://your-project.vercel.app/mcp

Usage notes

Usage examples you can try after the server is running include asking to show your last Lichess game, requesting Stockfish analysis, comparing engine evaluations across Stockfish, Maia2, and Leela, or analyzing your openings from a chessboard setup.

ChessAgine.Skill

To properly use ChessAgine MCP, provide a Skill file that describes how to utilize the MCP capabilities for your LLM.

Deploy your own instance

You can deploy your own ChessAgine MCP instance on Vercel with a few clicks.

1. Fork this repository
2. Go to vercel.com/new and import your fork
3. No environment variables needed — just deploy
4. Your server will be at https://your-project.vercel.app/mcp

Dev commands

The development workflow uses standard npm scripts to build and run the MCP server.

npm run build:mcp  # Builds the mcp server layer which generates mcpb file
npm run build:ui   # Builds the ChessAgine MCP UI html files
npm run build      # Builds entire project, use for local development
npm run start      # starts the MCP server
npm run debug      # opens MCP inspector to inspect new changes made

Security and notes

No sensitive credentials are embedded in this setup. When deploying publicly, manage access to the MCP endpoint through your hosting platform and follow best practices for securing engine access and game data.

Available tools

render_board

Renders the current chess board from the active game or position for visual analysis.

stockfish_analyze

Runs Stockfish on the current position to provide evaluation and principal variation analysis.

maia2_engine

Access Maia2 neural engine evaluations for alternative strategic insights.

leela_engine

Access Leela neural engine evaluations for human-like strategic consideration.

elite_leela_engine

Access Elite Leela engine evaluations for advanced search and evaluation.

opening_database

Query opening databases to fetch known lines and repertoire suggestions.

lichess_games

Fetch and render Lichess games related to a user or position for study.

render_pgn

Render full PGN games or specific variations for visualization and analysis.