A comprehensive Model Context Protocol (MCP) server that provides advanced chess analysis capabilities by implementing Chess Context Protocol Server and integrating Stockfish engine evaluation, positional theme analysis, opening databases, puzzle training, game visualization, and chess knowledge for enhanced chess understanding and gameplay improvement.
- Stockfish Integration: Deep engine analysis with configurable search depth
- Theme Analysis: Evaluate material, mobility, space, positional factors, and king safety
- Variation Analysis: Compare multiple lines and track positional changes
- Move Validation: Check move legality and generate board state descriptions
- Game Review: Comprehensive game analysis with theme progression and critical moments
- Visual Board Rendering: Generate HTML chess boards for any position
- Dynamic Game Viewer: Interactive game replay with move navigation
- Puzzle Training: Access Lichess puzzle database with theme filtering
- Game Fetching: Retrieve user games from Lichess for analysis
- Lichess Master Games: Access master-level opening statistics and games
- Lichess User Games: Analyze how positions are played across skill levels
- Lichess Puzzle Database: 3+ million tactical puzzles with theme-based filtering
- ChessDB: Query extensive game databases for move evaluations and statistics
- Chess Principles: Silman's imbalances and Fine's 30 principles
- Endgame Theory: Essential endgame knowledge and patterns
- Strategic Concepts: Comprehensive chess improvement guidelines
- Puzzle Themes: 150+ tactical motifs and patterns
Download the chessagine-mcp.mcpb file and install it directly in Claude Desktop:
- Download the latest release from GitHub releases
- Open Claude Desktop
- Go to Settings → Extensions → Install from file
- Select the
chessagine-mcp.mcpbfile - Restart Claude Desktop
- Node.js 20+
- npm or yarn package manager
git clone https://github.com/jalpp/chessagine-mcp.git
cd chessagine-mcp
npm install
npm run buildAdd to your claude_desktop_config.json:
macOS/Linux:
{
"mcpServers": {
"chessagine-mcp": {
"command": "node",
"args": ["/absolute/path/to/chessagine-mcp/build/mastra/stdio.js"]
}
}
}Windows:
{
"mcpServers": {
"chessagine-mcp": {
"command": "node",
"args": ["C:\\absolute\\path\\to\\chessagine-mcp\\build\\mastra\\stdio.js"]
}
}
}Analyze this position: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1
Show me the board for this position: r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3
Review this game and identify critical moments:
[Event "Casual Game"]
[White "Player1"]
[Black "Player2"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 a6...
Give me a tactical puzzle rated between 1500-1800 with a fork theme
Show me the recent games for Lichess user "Magnus_Carlsen"
Create an interactive viewer for this game: https://lichess.org/abc12345
What are the master games for the Sicilian Defense after 1.e4 c5 2.Nf3 d6?
Run Stockfish analysis on this position at depth 15: r1bqk2r/pppp1ppp/2n2n2/2b1p3/2B1P3/3P1N2/PPP2PPP/RNBQK2R w KQkq - 4 5
Compare these variations from the starting position:
1. e4 e5 2.Nf3 Nc6 3.Bb5
2. e4 e5 2.Nf3 Nc6 3.Bc4
3. e4 e5 2.Nf3 Nc6 3.d4
Analyze how the king safety theme changes in this line: 1.e4 e5 2.f4 exf4 3.Bc4 Qh4+ 4.Kf1
| Tool | Description |
|---|---|
| Position Analysis | |
get-theme-scores |
Analyze positional themes for strategic evaluation |
analyze-variation-themes |
Track theme evolution across move sequences |
get-theme-progression |
Monitor specific theme development |
compare-variations |
Side-by-side variation analysis |
find-critical-moments |
Identify key turning points |
| Engine & Evaluation | |
get-stockfish-analysis |
Deep engine position analysis |
get-stockfish-move-analysis |
Post-move position evaluation |
is-legal-move |
Move validation |
boardstate-to-prompt |
Convert positions to text descriptions |
| Knowledge & Database | |
get-chess-knowledgebase |
Access comprehensive chess knowledge |
get-lichess-master-games |
Master game database queries |
get-lichess-games |
User game statistics |
get-chessdb-analysis |
ChessDB position analysis |
| Visualization | |
generate-chess-board-view-artifact-using-html |
Render chess board in HTML |
generate-dynamic-gameview-html |
Create interactive game viewer |
| Puzzle Training | |
fetch-chess-puzzle |
Fetch puzzles from Lichess (filter by theme/rating) |
get-puzzle-themes |
List all available puzzle themes |
| Game Analysis | |
fetch-lichess-games |
Fetch user's 20 most recent games |
fetch-lichess-game |
Fetch specific game by URL or ID |
generate-game-review |
Generate detailed game review with themes |
parse-pgn-into-fens |
Convert PGN to FEN position list |
| Prompt | Description |
|---|---|
analyze-position |
Comprehensive positional analysis |
ChessAgine MCP now includes access to Lichess's extensive puzzle database with:
- 3+ Million Puzzles: Tactical problems for all skill levels
- 150+ Themes: Fork, pin, skewer, mate patterns, endgames, and more
- Rating Filter: Find puzzles matching your skill level (500-3000+)
- Theme Combinations: Query multiple themes simultaneously
- Instant Feedback: Validate solutions with engine analysis
- Tactical Motifs: fork, pin, skewer, discoveredAttack, deflection
- Checkmate Patterns: mateIn1, mateIn2, mateIn3, backRankMate, smotheredMate
- Endgame Skills: pawnEndgame, rookEndgame, queenEndgame, promotion
- Strategic Elements: zugzwang, clearance, interference, attraction
The new game review system provides comprehensive analysis:
- Theme Progression: Track material, mobility, space, positional play, and king safety
- Critical Moments: Automatically identify turning points in the game
- Visual Analytics: Generate charts and graphs of theme evolution
- Format Options: JSON data or human-readable text reports
- Configurable Threshold: Adjust sensitivity for detecting critical moments
The server integrates with several chess APIs:
- Lichess Explorer API: Opening statistics and master games
- Lichess Puzzle API: Tactical puzzle database with 3M+ positions
- Lichess Game API: User game history and specific game fetching
- ChessDB API: Position analysis and move databases
- Stockfish API: Engine evaluation and analysis
npm run build:mcp # Build the project
npm run dev # Development mode with watch
npm run clean # Clean build directory- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Discord: Join ChessAgine community
- GitHub Issues: Report bugs or request features
- Documentation: Full documentation
This project is licensed under the MIT License. See the LICENSE file for details.
- Stockfish: The powerful chess engine powering analysis
- Lichess: Open-source chess platform providing game data and puzzles
- ChessDB: Comprehensive chess position database
- Anthropic: Model Context Protocol specification and tools
@jalpp