Chess Context

ChessContext MCP

[](https://codecov.io/gh/rutvij26/chess-context)

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](docs/installation.md).

---

Tools

| Tool | Description | Example Prompt | |------|-------------|----------------| | analyze_position | Semantic analysis of a FEN position | "Analyze this position: [FEN]" | | analyze_game | Full game review from PGN or Lichess URL | "Review my game: [Lichess URL]" | | get_player_stats | Player profile, ratings, and opening repertoire | "Get hikaru's stats on chess.com" | | scout_opponent | Pre-game scouting report with strategic recommendations | "Scout [username] on lichess, I'm playing white" |

Full tool schemas and example outputs: [docs/tools.md](docs/tools.md)

---

Configuration

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

| Variable | Default | Description | |----------|---------|-------------| | STOCKFISH_API_URL | http://localhost:8090 | URL of Docker Stockfish engine | | STOCKFISH_DEPTH | 18 | Default search depth for position analysis | | STOCKFISH_QUIET_DEPTH | 12 | Depth for quiet positions in game analysis | | STOCKFISH_TIMEOUT | 30000 | Engine timeout in milliseconds | | ENABLE_LICHESS_CLOUD | false | Try Lichess cloud eval before local engine | | LICHESS_TOKEN | (none) | Optional Lichess API token for higher rate limits |

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](docs/architecture.md)

---

Roadmap

See [ROADMAP.md](ROADMAP.md) for the full milestone checklist.

---

Contributing

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

License

MIT — see [LICENSE](LICENSE)

Source & license

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

• Author: rutvij26
• Source: rutvij26/chess-context
• License: MIT
• Homepage: https://rutvij26.github.io/chess-context/

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