gambit
Gambit is an MCP chess server for validated position facts, bounded Stockfish analysis, PGN/game review, opening/repertoire/tablebase lookup, and local teaching/playing workflows.
Inspect FEN positions, list legal moves, explain board state, and analyze pawn structure.
Run Stockfish on positions, batches, candidate moves, moves, games, and endgames; compare moves and assess evidence.
Recognize/analyze chessboard images locally.
Parse PGNs, analyze/review games, manage/resume/cancel background jobs, and retrieve immutable analyses.
Import/search opening plans, statistics, TSV corpora, studies, and repertoires; query coverage and opening positions.
Run teaching sessions, hints, move feedback, concept progress, lessons, puzzles/tactics, repertoire drills, and tutor turns.
Use progressive analysis, metrics, tablebase diagnostics/results, speech plans, and local WAV synthesis exposed by the schema.
Serve MCP over stdio or streamable HTTP and support a localhost playing workspace.
Note: the schema exposes learner-profile, speech-synthesis, and tablebase tools even though the README lists those among unsupported features.
Connects the server outbound to OpenAI's secure MCP tunnels via the official tunnel client, exposing Gambit's analyses over a loopback HTTP endpoint so it can be added as a ChatGPT developer-mode app using a tunnel for its connection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gambit review my last game and explain my biggest blunder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
1. Introduction
Gambit is an MCP server that gives connected hosts validated chess facts, bounded local Stockfish analysis, attributed API information, and a localhost playing workspace. The connected host writes the explanations and handles audio.
Related MCP server: Chess Engine MCP Server
2. Usage
Install Python 3.14.7, uv 0.12.10, Node.js 24.22.0, npm 11.19.1, Task 3.54.0, and Stockfish. Then initialize and start the server:
uv sync --locked --extra vision
uv run gambit initialize
uv run gambit.env.example documents the optional settings. Keep real credentials private. showcase/configuration.toml shows TOML configuration, and uv run gambit serve --transport streamable-http --port 3025 serves MCP over HTTP.
2.1. Playing Workspace
Build the sibling ../chessboard checkout first. Then build the interface and start the workspace:
npm ci --prefix ui
npm run build --prefix ui
uv run gambit play --port 30303. Features
Position facts, batch analysis, and move comparisons.
PGN validation and board recognition.
Opening classifications.
Opt-in, attributed provider requests.
Temporary live games.
Contract version 3 preserves White-relative scores, history identity, units, attribution, search bounds, and revision checks.
Only opening classifications and non-personal configuration persist. Games, evidence, jobs, and API caches stay bounded and process-local. Gambit doesn't support learner profiles, personalized databases, server-authored explanations, speech synthesis, local tablebases, or bulk personal downloads.
4. Architecture
src/gambit/ separates providers, knowledge, game evidence, local engines, live state, and MCP and HTTP transport. ui/src/ owns browser presentation and uses sibling Chessboard events. Stale revisions never publish annotations, rejected optimistic moves roll back, hints hide solutions, and opponent strength stays separate from evidence analysis.
HTTP binds to loopback and validates the peer, host, origin, request type, and size. GAMBIT_UI_ORIGIN can allow one exact HTTPS .ts.net origin through loopback. Forwarded headers never replace the peer.
4.1. Conventions
Never persist personal identifiers or response bodies in logs.
Preserve the existing remote MCP connection.
Don't add Python comments or docstrings.
4.2. Verification
Backend checks use uv run --locked --extra vision pytest. Explicit style checks use uv run ruff check src tests tools/scripts and uv run python tools/scripts/format_code.py --check. tools/scripts/generate_tutor_skill.py --check validates the portable .ai/skills/chess/ output against the authoritative Agents sources.
5. Dependencies
Dependency | Version | Use |
| 2.3.0 | Runtime: MCP server |
| 1.999 | Runtime: chess rules and engine protocol |
| 1.2.4 | Runtime: environment configuration |
| 0.28.1 | Runtime: provider requests |
| 2.5.4 | Optional |
| 1.31.0 | Optional |
| 13.0.0 | Optional |
| 1.9.0 | Development: source formatting checks |
| 9.1.1 | Development: tests |
| 1.4.1 | Development: asynchronous tests |
| 0.17.2 | Development: static checks |
|
| Build: package backend |
ui/README.md lists the browser workspace's dependencies.
6. Roadmap
Contract version 3 and the temporary live workspace.
Revalidate remote and voice behavior separately when deployment is requested.
7. Contributing
Read AGENTS.md and the applicable skills in .ai/skills/ before contributing. Set up the development environment with uv sync --locked --extra vision. Follow the repository conventions, preserve supported behavior, and add relevant tests for behavior changes. Run uv run --locked --extra vision pytest and uv build --out-dir build/packages before opening a pull request. Describe the change, its purpose, and the validation results in the pull request.
8. License
gambit is licensed under the MIT license. See LICENSE for the complete license text.
Available Tools
58 toolsadvance_lessonC
Mark a lesson step complete without equating completion to demonstrated mastery.
Inputs: step (required), lesson_id (required). Returns: object
analyze_chessboardB
Recognize a chessboard image and analyze it with Stockfish in one fast call. Intended for axis-aligned screenshots and diagrams. Unreliable OCR is rejected by default so analysis is not based on a silently wrong board.
Inputs: image (required), nodes, multipv, orientation, +3 more. Returns: object
analyze_gameC
Analyze a complete standard-chess PGN with adaptive Stockfish searches. Scores use White's perspective; nodes is the configured per-position budget.
Inputs: pgn (required), side, multipv, initial_nodes, +2 more. Returns: moves, engine, result, headers, +1 more
analyze_pawn_structureB
Return factual isolated, doubled, and passed-pawn geometry for both sides.
Inputs: fen (required). Returns: object
analyze_positionB
Analyze a FEN position with Stockfish. Evaluations are from the side-to-move perspective.
Inputs: fen (required), nodes, multipv. Returns: object
analyze_positionsC
Analyze a batch of FEN requests through one warm Stockfish process. All scores use White's perspective.
Inputs: positions (required). Returns: result
assess_candidate_moveC
Verify a candidate against unrestricted and forced-root searches at two budgets, retaining full supplied history.
Inputs: fen (required), move (required), history. Returns: fen, caveat, history, root_fen, +6 more
cancel_analysis_jobB
Cancel a job at its next search boundary. An active search has a bounded deadline.
Inputs: job_id (required). Returns: object
cancel_progressive_analysisB
Cancel queued or running progressive analysis and mark its result stale.
Inputs: request_id (required). Returns: error, status, context_id, request_id, +2 more
compare_candidate_movesC
Analyze and compare up to eight candidate moves under the same search profile.
Inputs: fen (required), moves (required), history, profile. Returns: object
create_game_lessonsC
Create up to twenty position-specific practice lessons from the learner's mistakes in a saved game analysis.
Inputs: side (required), learner_id (required), analysis_id (required). Returns: lessons, grouping, schema_version
create_repertoire_drillC
Create a repertoire recall drill without exposing its expected moves.
Inputs: fen (required), learner_id (required). Returns: object
create_tutor_turnC
Create a grounded tutor turn with engine evidence, teaching guidance, board actions, and speech segments.
Inputs: fen (required), intent, history, profile, +2 more. Returns: object
evaluate_endgameC
Combine endgame features with tablebase evidence or engine analysis when unavailable.
Inputs: fen (required). Returns: object
evaluate_moveB
Compare a legal move against engine analysis before and after it. Scores are White-relative.
Inputs: fen (required), move (required), history, profile. Returns: object
evaluate_positionC
Analyze a position with White-relative scores, immutable evidence, and optional move history.
Inputs: fen (required), moves, profile. Returns: id, fen, engine, profile, +9 more
explain_positionB
Inspect legal state, material, pins, attacks, and pawn structures without an engine.
Inputs: fen (required). Returns: object
find_openingB
Search locally imported opening names with pagination.
Inputs: query (required), offset. Returns: result
get_analysisC
Retrieve an immutable position analysis or completed game report.
Inputs: analysis_id (required). Returns: object
get_analysis_jobC
Read analysis job status and completed-search progress.
Inputs: job_id (required). Returns: object
get_analysis_metricsB
Report bounded engine latency samples, queue delays, cache hits, and reserved interactive capacity.
Inputs: no named parameters. Returns: cache_hits, queue_p95_ms, sample_count, search_count, +5 more
get_capabilitiesA
Report engine settings and exact local corpus counts without launching an engine.
Inputs: no named parameters. Returns: object
get_concept_progressC
Return concept-specific attempts, independent successes, and due review dates.
Inputs: learner_id (required). Returns: concepts, schema_version
get_due_repertoire_drillB
Select a due repertoire position using transposition-aware spaced review and hide expected moves.
Inputs: learner_id (required). Returns: object
get_learner_progressC
Read persisted learner preferences and a paginated training-progress view.
Inputs: learner_id (required), offset. Returns: object
get_opening_coverageB
Report exact local opening coverage by source, keeping theoretical plans and practical statistics distinct.
Inputs: no named parameters. Returns: sources, source_limit, schema_version, is_exhaustive_chess_coverage
get_opening_plansC
Retrieve transposition-matched opening plans separately from practical game statistics.
Inputs: fen (required). Returns: plans, caveat, schema_version, practical_statistics
get_opening_positionC
Get source-attributed corpus moves at a position, including transpositions.
Inputs: fen (required), offset. Returns: object
get_progressive_analysisC
Read progressive analysis status and its completed evidence ID, withholding stale results.
Inputs: request_id (required). Returns: error, status, context_id, request_id, +2 more
get_repertoire_moveC
Get personal repertoire moves at a position.
Inputs: fen (required), offset. Returns: object
get_speech_planC
Create interruptible speech segments and legal SAN/UCI pronunciations.
Inputs: fen (required), segments (required), moves. Returns: object
get_tablebase_diagnosticsA
Inspect configured tablebase directories and WDL/DTZ file pairing without claiming complete coverage.
Inputs: no named parameters. Returns: caveat, dtz_files, wdl_files, directories, +4 more
get_tablebase_resultC
Probe configured local Syzygy WDL and DTZ with explicit availability and draw semantics.
Inputs: fen (required). Returns: object
get_tacticB
Select a due puzzle near the learner's rating and begin a solution-hidden session.
Inputs: learner_id (required), theme. Returns: object
get_teaching_hintB
Reveal one of four progressive hint levels, recording assistance without exposing the full solution early.
Inputs: level (required), session_id (required). Returns: fen, status, concept, question, +3 more
import_opening_planB
Import a dated, versioned opening teaching plan with source attribution. Advice is not engine-verified automatically.
Inputs: plan (required). Returns: id, fen, name, plans, +10 more
import_opening_statisticsC
Import source-attributed aggregate opening outcomes for an explicitly described game population.
Inputs: fen (required), move (required), draws (required), source (required), +4 more. Returns: id, draws, source, move_uci, +6 more
import_opening_tsvC
Import a bounded Lichess-format opening TSV batch with explicit source attribution.
Inputs: tsv (required), source (required). Returns: object
import_puzzlesC
Import a bounded puzzle CSV batch, validating the setup move and complete source line.
Inputs: source (required), csv_text (required). Returns: object
import_studyC
Import a source-attributed PGN study, including variations and transpositions.
Inputs: pgn (required), name (required), source (required), is_repertoire. Returns: object
initialize_openingsB
Load the bundled, version-pinned Lichess named opening corpus into local storage.
Inputs: no named parameters. Returns: object
inspect_positionA
Inspect a FEN position without engine analysis.
Inputs: fen (required). Returns: object
list_legal_movesB
List legal moves from a FEN position in SAN and UCI notation.
Inputs: fen (required). Returns: object
parse_gameA
Parse one standard-chess PGN without Stockfish. Plies are one-based from the supplied starting position.
Inputs: pgn (required). Returns: moves, result, headers, initial_fen
recognize_chessboardA
Convert an axis-aligned 2D chessboard screenshot or book diagram to FEN locally. Pass image as a local path, file URL, raw base64, or base64 data URL. Returns confidence and reliability; do not silently trust a result whose reliable or plausible field is false.
Inputs: image (required), orientation, side_to_move, infer_castling_rights. Returns: object
record_training_attemptC
Record an explicitly reported training outcome with idempotent attempt identity.
Inputs: puzzle_id (required), attempt_id (required), learner_id (required), was_successful (required). Returns: object
resume_analysis_jobA
Resume an interrupted, failed, or cancelled game job using compatible durable search checkpoints.
Inputs: job_id (required). Returns: id, pgn, error, status, +5 more
review_gameB
Analyze and classify a complete PGN with deterministic Gambit review labels and per-player summaries. No prose coaching is generated.
Inputs: pgn (required), side, multipv, initial_nodes, +2 more. Returns: moves, engine, result, headers, +2 more
start_analysis_jobC
Start a bounded, persistent background game analysis or review job.
Inputs: pgn (required), should_review. Returns: object
start_lessonC
Start a persisted lesson in tactics, openings, middlegames, positioning, endgames, or calculation.
Inputs: topic (required), learner_id (required). Returns: object
start_progressive_analysisA
Return immediate preliminary evidence and queue deeper analysis; supersede older requests with the same context ID.
Inputs: fen (required), context_id (required), history. Returns: status, context_id, request_id, preliminary, +2 more
start_teaching_sessionC
Start a solution-hidden teaching cycle with a concept-specific learning objective.
Inputs: fen (required), history, learner_id. Returns: fen, status, concept, question, +3 more
submit_repertoire_moveC
Submit a legal move to a repertoire recall drill.
Inputs: move (required), session_id (required). Returns: object
submit_tactic_moveC
Check a puzzle move, play the source reply, and schedule completed puzzles for review.
Inputs: move (required), session_id (required). Returns: object
submit_teaching_moveC
Assess an answer, explain verified candidate lines, update concept progress, and schedule review.
Inputs: move (required), session_id (required). Returns: due_at, assessment, session_id, explanation, +3 more
synthesize_speechB
Synthesize a short local WAV using espeak-ng. Returns a local file URI, not streamed audio.
Inputs: text (required), rate, voice. Returns: object
tutor_moveB
Assess a proposed legal SAN or UCI move. Returns the resulting position and Stockfish's best replies, for move-by-move tutoring.
Inputs: fen (required), move (required), nodes, multipv. Returns: object
update_learner_profileC
Persist a learner's rating band, teaching preferences, and voice settings.
Inputs: learner_id (required), style, voice, detail, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 58 tools
Many tools overlap heavily: analyze_position, evaluate_position, analyze_positions, inspect_position, and explain_position all inspect or evaluate a FEN, while analyze_game, review_game, start_analysis_job, and get_analysis all analyze entire games. Move assessment is similarly fragmented across evaluate_move, compare_candidate_moves, tutor_move, assess_candidate_move, and submit_teaching_move. Descriptions attempt to differentiate, but the agent must read carefully to avoid picking the wrong tool.
All tool names use snake_case and mostly follow a verb_noun pattern (e.g., create_game_lessons, get_opening_plans, start_progressive_analysis). Minor deviations exist, such as 'inspect_position' vs 'analyze_position' and 'tutor_move' vs 'evaluate_move', but the overall convention is predictable and readable.
With 58 tools, the set is far beyond a reasonable scope, and many tools duplicate functionality (e.g., multiple analysis and evaluation endpoints). The domain is broad (engine analysis, openings, repertoire, tutoring, speech, tablebases), but the sheer number creates a heavy, confusing surface that is not well-scoped.
The surface covers a wide range of chess analysis and teaching workflows: engine evaluation, game review, openings, repertoire drills, tactics, tablebases, speech synthesis, and learner progress. Minor gaps include no deletion or update for some entities (e.g., no delete_repertoire, no update_game_lesson), but the core lifecycle operations are present.
Related MCP Connectors
Pedagogical chess intelligence for AI agents: explain positions and games for a target Elo.
Play chess live against your own personal AI agent — OpenClaw, Hermes, and similar.
Review your Chess.com and Lichess games with Stockfish on an interactive board, in plain words.
Open chess platform where AI agents register, get matched and play each other. Referee only.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables comprehensive chess analysis through Stockfish engine integration, positional evaluation, puzzle training, game review, and access to extensive chess databases. Provides visual board rendering, interactive game viewers, and tactical puzzle training with 3+ million problems from Lichess.34AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to perform professional-grade chess analysis using Stockfish and optionally Leela Chess Zero, including position analysis, full game review, opening lookup, and puzzle generation.12 npm2MIT
- AlicenseAqualityDmaintenanceA hybrid AI chess coach MCP server that uses Stockfish for grounded evaluation and LLM for natural-language coaching, enabling game analysis, weakness diagnosis, and personalized drills from your own games.630 PyPI5MIT
- AlicenseAqualityBmaintenanceMCP chess runtime that lets LLMs play, analyze, and adapt strength by exposing Stockfish, human move likelihood (Maia3), and Lichess statistics, with the LLM handling strategy and the server handling computation.1329 npmAGPL 3.0