Skip to main content
Glama

ChessAgine MCP

by jalpp

ChessAgine MCP

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.

Preview

Features

🔧 Core Analysis Tools

  • 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

🎮 Interactive Features

  • 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

📊 Database Integration

  • 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

🧠 Knowledge Base

  • 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

Installation

Option 1: Using MCPB File (Recommended)

Download the chessagine-mcp.mcpb file and install it directly in Claude Desktop:

  1. Download the latest release from GitHub releases

  2. Open Claude Desktop

  3. Go to Settings → Extensions → Install from file

  4. Select the chessagine-mcp.mcpb file

  5. Restart Claude Desktop

Option 2: Local Development Setup

Prerequisites

  • Node.js 20+

  • npm or yarn package manager

Clone and Setup

git clone https://github.com/jalpp/chessagine-mcp.git cd chessagine-mcp npm install npm run build

Configure Claude Desktop

Add 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"] } } }

Usage Examples

Basic Position Analysis

Analyze this position: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1

Visual Board Display

Show me the board for this position: r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3

Game Review

Review this game and identify critical moments: [Event "Casual Game"] [White "Player1"] [Black "Player2"] 1. e4 e5 2. Nf3 Nc6 3. Bb5 a6...

Puzzle Training

Give me a tactical puzzle rated between 1500-1800 with a fork theme

Fetch User Games

Show me the recent games for Lichess user "Magnus_Carlsen"

Interactive Game Viewer

Create an interactive viewer for this game: https://lichess.org/abc12345

Opening Exploration

What are the master games for the Sicilian Defense after 1.e4 c5 2.Nf3 d6?

Engine Analysis

Run Stockfish analysis on this position at depth 15: r1bqk2r/pppp1ppp/2n2n2/2b1p3/2B1P3/3P1N2/PPP2PPP/RNBQK2R w KQkq - 4 5

Variation Comparison

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

Theme Analysis

Analyze how the king safety theme changes in this line: 1.e4 e5 2.f4 exf4 3.Bc4 Qh4+ 4.Kf1

Available Tools

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

Available Prompts

Prompt

Description

analyze-position

Comprehensive positional analysis

Puzzle Training Features

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

Popular Puzzle Themes

  • 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

Game Review System

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

API Integration

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

Development

Building from Source

npm run build:mcp # Build the project npm run dev # Development mode with watch npm run clean # Clean build directory

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Support

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

  • 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

Authors

@jalpp

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables 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.

  1. Preview
    1. Features
      1. 🔧 Core Analysis Tools
      2. 🎮 Interactive Features
      3. 📊 Database Integration
      4. 🧠 Knowledge Base
    2. Installation
      1. Option 1: Using MCPB File (Recommended)
      2. Option 2: Local Development Setup
    3. Usage Examples
      1. Basic Position Analysis
      2. Visual Board Display
      3. Game Review
      4. Puzzle Training
      5. Fetch User Games
      6. Interactive Game Viewer
      7. Opening Exploration
      8. Engine Analysis
      9. Variation Comparison
      10. Theme Analysis
    4. Available Tools
      1. Available Prompts
        1. Puzzle Training Features
          1. Popular Puzzle Themes
        2. Game Review System
          1. API Integration
            1. Development
              1. Building from Source
            2. Contributing
              1. Support
                1. License
                  1. Acknowledgments
                    1. Authors

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/jalpp/chessagine-mcp'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server