Chessagine MCP Server: Stockfish, Positional Themes, Knowledgebase

Overview

The Chessagine MCP Server provides a compact toolset for programmatic chess analysis. It integrates Stockfish evaluations, positional-theme extraction, Lichess opening-database lookups, and a searchable chess knowledgebase into a single server that can be called from other services or language models via the Model Context Protocol (MCP). This makes it simple to augment game annotations, create opening explorers, or let an LLM call chess-aware tools during a conversation.

The server is useful for developers building analysis dashboards, tutoring systems, or LLM integrations that need deterministic chess insights. Instead of running multiple separate components, Chessagine exposes them via consistent endpoints (or MCP tool calls) so you can request evaluations, retrieve thematic commentary, or query historical opening statistics in one workflow.

Features

• Stockfish position evaluation and multi-depth analysis (score, best lines)
• Positional theme extraction (positional motifs and human-readable themes)
• Lichess opening-database queries (popularity, win/draw/loss stats by SAN or FEN)
• Searchable, queryable chess knowledgebase (position → annotated insights)
• Batch PGN analysis and per-move metadata
• HTTP API and MCP-compatible tool endpoints for LLM integrations
• Docker-friendly setup and configurable environment variables

Installation / Configuration

Clone the repository, configure environment variables, then run via Docker Compose or locally. Example steps:

1. Clone the repo

git clone https://github.com/jalpp/chessagine-mcp.git
cd chessagine-mcp

2. Configure environment variables (create a .env file)

# .env (example)
STOCKFISH_PATH=/usr/local/bin/stockfish
DATABASE_URL=postgresql://user:password@localhost:5432/chessagine
LICHESS_DB_PATH=/data/lichess_db
PORT=8080

3a. Start with Docker Compose (recommended)

docker-compose up --build

3b. Or run locally (Python example)

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# initialize database (example)
alembic upgrade head
uvicorn chessagine.server:app --host 0.0.0.0 --port ${PORT:-8080}

Notes:

• Ensure Stockfish binary is accessible and its path is set in STOCKFISH_PATH.
• Point LICHESS_DB_PATH to an extracted Lichess opening DB file (or provide a custom opener).
• Database migrations/schema initialization may be required (alembic/migrations or equivalent).

Available Tools / Resources

The server exposes several named tools/endpoints. Example endpoints and parameters:

Example: request a position evaluation and themes in one call

curl -X POST http://localhost:8080/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "fen": "r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 2 3",
    "depth": 20,
    "include_themes": true
  }'

Response typically includes: engine score (centipawns), best moves/pv, tablebase/refutation info (if available), and extracted themes like “king-side pawn majority”, “weak d5 square”, or “bishop pair advantage”.

Use Cases

• Annotate a game with engine evaluations and theme notes

  • Upload a PGN to /api/annotate-pgn, receive per-move evaluations, best lines, and theme annotations for each move to populate a viewer or a study guide.

• Build an opening explorer

  • Query /api/openings with move sequences (e.g., “e4 e5 Nf3 Nc6”) to get Lichess-sourced statistics and common continuations; use those stats to show popularity and results in a UI.

• LLM-assisted chess tutor

  • Expose the MCP tools to a language model so it can call Stockfish and theme extraction when answering coaching questions (e.g., “Show me why 15…Nd5 is bad here”). The LLM can call /api/evaluate and /api/themes, then synthesize a natural-language explanation.

• Generate training drills

  • Search the knowledgebase for motifs like “back-rank mate” or “isolated queen’s pawn endgame”, fetch sample positions, and create targeted puzzles or drills.

• Batch analysis pipeline

  • Periodically run large PGN collections through the batch analysis endpoint to populate a database of annotated games, then query it for research or statistics.

Tips for Developers

• Start by running the server locally and calling the basic /api/evaluate endpoint to confirm Stockfish is configured.
• Use Docker Compose for production-like deployments and to isolate dependencies.
• If integrating with an LLM via MCP, expose only the necessary tools and sanitize inputs/outputs to avoid leaking sensitive data.
• Monitor resource usage: Stockfish analysis at high depths is CPU-intensive; consider a worker queue for large batch jobs.

For more specifics on endpoint schemas, response formats, and deployment examples, consult the repository README and the API reference in the repo.