chess-context MCP server
Commit Nov 13, 2026Provides Claude with semantic chess intelligence including position analysis, game reviews, and opponent scouting with strategic narratives.
Also known as rutvij26/chess-context
- Stars
- 6
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is chess-context MCP?
chess-context provides Claude with semantic chess intelligence including position analysis, game reviews, and opponent scouting with strategic narratives. It exposes 4 tools, such as analyze_position, analyze_game, get_player_stats.
Summary generated from the project's README
About chess-context MCP server
Providing strategic chess narratives and position analysis to Claude is what this MCP server enables for chess players and enthusiasts. It moves beyond simple engine evaluations by translating raw numbers into semantic insights about pawn structures, piece activity, and tactical themes. Users can integrate this with Claude Desktop or Cursor to receive detailed explanations of why certain moves are preferred in specific middlegame or endgame scenarios.
Developers can set this up locally using Node.js and Docker Desktop to run a multi-threaded Stockfish engine for high-speed analysis. If Docker is unavailable, the server automatically falls back to a built-in WASM engine. The system connects to Lichess and Chess.com APIs to fetch player statistics and game data. Users can customize the experience by configuring environment variables like STOCKFISH_DEPTH or providing a LICHESS_TOKEN to increase API rate limits.
Written from the project's README. Every use case is checked against a quote from it.
chess-context MCP tools 4
Detected from the READMEanalyze_positionanalyze_gameget_player_statsscout_opponent
Configuration
LICHESS_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerutvij26/chess-context is public and reachablegithub.com/rutvij26/chess-context ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/rutvij26/chess-context ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubChessContext 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
| 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
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
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
chess-context MCP questions
What tools does chess-context MCP provide?
It exposes 4 tools, including analyze_position, analyze_game, get_player_stats, scout_opponent.
What happens if I don't have Docker installed?
The server will automatically fall back to a built-in WASM engine, though you may experience a 30–60s warmup and slower analysis speeds.
Can I use this to scout opponents on Lichess?
Yes, the scout_opponent tool allows you to generate pre-game scouting reports with strategic recommendations based on a player's Lichess profile.
How does the engine selection work?
The Engine Router automatically selects the fastest available engine, prioritizing Docker Stockfish, then a WASM worker pool, and finally single-threaded WASM.