ChessContext MCP

Semantic chess intelligence for Claude. Not just engine numbers — context, narrative, and strategic insight.

Instead of best move: Nf3 (+0.4), ChessContext gives Claude:

"The position is a Sicilian structure entering the middlegame. An isolated queen pawn creates dynamic imbalance — White has active piece play while Black has a long-term structural target. A knight on e5 is anchored on an outpost with no enemy pawn to evict it. White holds a slight edge (+0.8). Best continuation: Nd5, a strong centralizing move that eyes the f4 square and threatens to exchange Black's key defensive piece."

Built on the Model Context Protocol — works with Claude Desktop, Cursor, and any MCP-compatible client.

Demo

You: Analyze this position for me: r1bqk2r/pppp1ppp/2n2n2/2b1p3/2B1P3/2NP1N2/PPP2PPP/R1BQK2R w KQkq - 4 5

Claude: [calls analyze_position]

The game is in the opening phase. The symmetrical pawn structure means the
game is balanced — the player with better piece activity will have the edge.
The bishop pair gives White long-term compensation in an open position.
Active, well-coordinated pieces give the better side significant attacking
potential. White holds a slight edge (+0.3).

Top moves:
1. O-O (castling — improves king safety and connects the rooks)
2. d4 — central pawn break, opening the c4 bishop's diagonal
3. Be3 — developing and preparing queenside play

You: Scout my opponent "MagnusCarlsen" on Lichess before our match. I'll be playing White.

Claude: [calls scout_opponent]

Magnus plays the Sicilian Defense in 45% of games as Black vs e4, and the
King's Indian against d4 (55%). His win rate drops significantly in simplified
positions — he has a 42% win rate in endgames vs his 61% overall.

Recommendation: Avoid the sharp Najdorf lines where he's most dangerous.
Consider the Rossolimo (3.Bb5) — leads to strategic positions and sidesteps
his preparation. Aim to trade pieces and reach a technical endgame.

Quick Start

Prerequisites: Node.js 20+, Docker Desktop (recommended)

git clone https://github.com/rutvij26/chess-context.git
cd chess-context/mcp-server
npm install && npm run build

# Start the Stockfish engine container (fast, multi-threaded)
docker compose up -d

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "chess-context": {
      "command": "node",
      "args": ["/absolute/path/to/chess-context/mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You're ready — try: "Analyze the starting chess position."

No Docker? The server falls back to a built-in WASM engine automatically — but expect a 30–60s warmup and slower game analysis.

For detailed setup instructions, see docs/installation.md.

Tools

Full tool schemas and example outputs: docs/tools.md

Configuration

Set these environment variables on the MCP server to customize behavior:

The Docker container has its own env vars in mcp-server/docker-compose.yml (STOCKFISH_THREADS, STOCKFISH_HASH).

{
  "mcpServers": {
    "chess-context": {
      "command": "node",
      "args": ["/path/to/chess-context/mcp-server/dist/index.js"],
      "env": {
        "LICHESS_TOKEN": "your_token_here"
      }
    }
  }
}

Architecture

┌─────────────────────────────────────────────────┐
│              LAYER 3: MCP TOOLS                 │
│  analyze_position · analyze_game                │
│  get_player_stats · scout_opponent              │
├─────────────────────────────────────────────────┤
│           LAYER 2: INTELLIGENCE                 │
│  Position Classifier · Theme Tagger             │
│  Narrative Generator · Critical Moments         │
├─────────────────────────────────────────────────┤
│            LAYER 1: FOUNDATION                  │
│  Engine Router · Docker Stockfish (primary)     │
│  WASM Stockfish (fallback) · LRU Cache          │
│  Chess.com API · Lichess API                    │
└─────────────────────────────────────────────────┘

Layer 1 handles raw compute. The Engine Router automatically selects the fastest available engine: Docker Stockfish (native binary, multi-threaded, HTTP) → WASM worker pool → single-threaded WASM. Chess.com/Lichess API clients handle game data.

Layer 2 transforms raw numbers into meaning: game phase detection, 10 pawn structure types, 15 tactical/strategic themes, template-based narratives, and critical moment detection (blunders, mistakes, missed wins).

Layer 3 wires everything into MCP tools registered with the Claude Desktop server.

Caching: Position evaluations are cached by FEN + depth (LRU, 500 entries). Player stats are cached with a 5-minute TTL. analyze_game on the same game twice takes milliseconds the second time.

Deep-dive: docs/architecture.md

Roadmap

See ROADMAP.md for the full milestone checklist.

Contributing

See CONTRIBUTING.md — adding themes, pawn structures, and new tools is straightforward and documented.

License

MIT — see LICENSE