Chess Trainer MCP Server

A comprehensive chess training application with AI-powered analysis using Stockfish NNUE engine and MCP (Model Context Protocol) integration for advanced coaching capabilities.

✨ Features

🎯 Core Chess Features

• Interactive Chess Board: Drag-and-drop interface with real-time move validation
• Real-time Engine Analysis: Stockfish NNUE WASM integration for local analysis
• Evaluation Bar: Visual representation of position evaluation with depth info
• Human vs AI: Play against AI with adjustable ELO (800-2800) and thinking time
• Human vs Human: Local multiplayer chess games
• Position Analysis: Get best moves and evaluations for any position

🎬 Replay & Learning

• Game Replay: Full replay system with controls (play, pause, step, speed)
• Sample Games: Built-in famous games (Scholar's Mate, Italian Game, Sicilian Defense)
• Move Navigation: Browse through game history with analysis
• Board Flipping: View games from both perspectives

🔄 Server-Authoritative Architecture

• Real-time Synchronization: All moves are validated and synchronized through the server
• WebSocket Communication: Instant updates across all connected clients
• State Persistence: Games are automatically saved to disk and survive server restarts
• Auto-Save: Games are saved every 30 seconds and on server shutdown
• Game Recovery: All active games are restored when the server restarts
• Unified Move Handling: Both human and AI moves follow the same server-sync flow

🤖 MCP Integration

• 14 Organized Chess Tools: Complete MCP tools for AI assistants
• Server Management: Launch and control the chess trainer server
• Game Management: Create, list, and manage chess games
• Game Interaction: Make moves and get AI suggestions
• Analysis Tools: Position analysis, move evaluation, and best move suggestions
• Utility Tools: FEN validation, PGN generation, and opening explanations

🚀 Quick Start

🎯 Web Interface (One-Command Setup)

# Run directly with npx - no installation needed!
npx chess-trainer-mcp

This will automatically:

• Install all dependencies
• Build the frontend
• Start the server on http://localhost:3456
• Open the chess interface in your browser

🎮 Playing Chess

1. Human vs Human: Default mode - take turns making moves
2. Human vs AI: Choose your color and AI difficulty
   • AI ELO range: 800-2800
   • Thinking time: 0.1s to 10s
   • AI automatically moves after your turn
3. Game Analysis: Use the evaluation bar and analysis tools
4. Replay Mode: Load and replay famous chess games

🏗️ Architecture

Client-Server Communication Flow

Move Made → Sync to Server → Server Validates → WebSocket Broadcast → Client Updates → Check AI Turn

Key Components

• Frontend: Svelte-based chess interface with Chessground board
• Backend: Node.js server with Express API and WebSocket support
• Engine: Stockfish NNUE for move analysis and AI play
• MCP Server: JSON-RPC interface for AI assistant integration

🤖 MCP Integration for AI Assistants

Chess Trainer MCP Server provides 15 well-organized chess tools that can be used by AI assistants like Claude, Cursor, and other MCP-compatible hosts.

Available Tools:

🚀 Server Management:

1. launch_chess_trainer - Launch the Chess Trainer web server with optional browser opening
2. stop_chess_trainer - Stop the Chess Trainer web server

🎮 Game Management: 3. create_game - Create a new chess game with specific settings (mode, AI ELO, color) 4. list_active_games - List all currently active chess games 5. get_game_state - Get the current state of a specific chess game 6. reset_game - Reset a game to the starting position

🎯 Game Interaction: 7. make_move - Make a move in an active chess game 8. suggest_best_move - Get the best move suggestion for the current position

📊 Analysis Tools: 9. analyze_position - Analyze a chess position (currently simulated, real Stockfish integration pending) 10. evaluate_move - Evaluate the quality of a chess move 11. get_best_moves - Get the top N best moves for a position

🔧 Utility Tools: 12. validate_fen - Validate a FEN string and get position information 13. generate_pgn - Generate PGN notation from a list of moves 14. explain_opening - Get explanation and principles of a chess opening

🌐 Web Access Tools: 15. get_embeddable_url - Get a URL to access the chess trainer web interface

🔧 MCP Host Configuration

🎯 Quick Configuration (Recommended)

Method 1: Using npx with --package flag

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "npx",
      "args": ["--package=chess-trainer-mcp", "chess-trainer-mcp-server"]
    }
  }
}

Method 2: Pre-install for faster startup

# First install globally
npm install -g chess-trainer-mcp

# Then configure
{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "chess-trainer-mcp-server"
    }
  }
}

🛠️ Host-Specific Configuration

Claude Desktop (Anthropic)

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "command": "npx",
      "args": ["--package=chess-trainer-mcp", "chess-trainer-mcp-server"]
    }
  }
}

Cursor IDE

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "npx", 
      "args": ["--package=chess-trainer-mcp", "chess-trainer-mcp-server"]
    }
  }
}

Continue.dev

Config file: ~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "chess-trainer-mcp",
      "command": "npx",
      "args": ["--package=chess-trainer-mcp", "chess-trainer-mcp-server"]
    }
  ]
}

Other MCP Hosts

{
  "servers": {
    "chess-trainer-mcp": {
      "transport": "stdio",
      "command": "npx",
      "args": ["--package=chess-trainer-mcp", "chess-trainer-mcp-server"]
    }
  }
}

🧪 Testing MCP Configuration

# Test server initialization
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx --package=chess-trainer-mcp chess-trainer-mcp-server

# Test tools discovery
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | npx --package=chess-trainer-mcp chess-trainer-mcp-server

# Test position validation
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"validate_fen","arguments":{"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"}}}' | npx --package=chess-trainer-mcp chess-trainer-mcp-server

📦 Installation Methods

Method 1: NPX (No Installation)

# Start web interface
npx chess-trainer-mcp

# Use as MCP server
npx --package=chess-trainer-mcp chess-trainer-mcp-server

Method 2: Global Installation

# Install globally
npm install -g chess-trainer-mcp

# Start web interface
chess-trainer-mcp

# Use as MCP server
chess-trainer-mcp-server

Method 3: Local Development

# Clone the repository
git clone https://github.com/modenl/stockfishmcp.git
cd stockfishmcp

# Install and build
npm run setup

# Start web interface
npm start

# Use as MCP server
node bin/mcp

🛠️ Command Options

# Web Interface Commands
npx chess-trainer-mcp                    # Start on default port 3456
npx chess-trainer-mcp --port 8080       # Start on custom port
npx chess-trainer-mcp --no-mcp          # Disable MCP integration
npx chess-trainer-mcp dev               # Development mode with hot reload
npx chess-trainer-mcp build             # Build frontend only
npx chess-trainer-mcp setup             # Install dependencies and build
npx chess-trainer-mcp help              # Show all available options

# MCP Server Commands
npx --package=chess-trainer-mcp chess-trainer-mcp-server  # Start MCP server
chess-trainer-mcp-server                                  # If globally installed

🎮 Usage Examples

Using with AI Assistants

Once configured, you can ask your AI assistant to:

🔍 Analysis Commands:

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

"What are the best moves for White in the starting position?"

"Explain the Italian Game opening"

"Validate this FEN: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

🎮 Game Management:

"Launch the chess trainer server"

"Create a new chess game with ID 'my-game' against AI with 1800 ELO"

"List all active chess games"

"Show me the current state of game session_12345"

🎯 Interactive Gameplay:

"Make the move e2e4 in game session_12345"

"Suggest the best move for game 'my-game'"

"Reset the chess game to starting position"

"Make a move and then suggest the opponent's best response"

💡 Advanced Interactions:

"Start a game, make the moves 1.e4 e5 2.Nf3, then analyze the position"

"Play the Italian Game opening and explain each move"

"Set up a game where I can practice the Sicilian Defense"

Web Interface Usage

1. Playing Chess:

   • Click "New Game" to start
   • Choose Human vs Human or Human vs AI
   • Configure AI strength (800-2800 ELO) and thinking time

2. Analysis:

   • Make moves on the board
   • Click "Analyze Position" for engine evaluation
   • View evaluation bar and best moves

3. Replay:

   • Click "Game Replay 📺" to open replay menu
   • Choose from current game or sample games
   • Use controls to navigate through moves

🏗️ Architecture

Web Server vs MCP Server

┌─────────────────────────────────────────────────────────┐
│                   User Commands                         │
│  npx chess-trainer-mcp  │  npx chess-trainer-mcp-server │
└─────────────┬───────────┴─────────────┬─────────────────┘
              │                         │
              ▼                         ▼
┌─────────────────────────┐   ┌─────────────────────────────┐
│     Web Server          │   │      MCP Server             │
│  (ChessTrainerServer)   │   │  (StdioMCPServer)          │
│  • Port 3456            │   │  • STDIO Communication     │
│  • Web Interface        │   │  • JSON-RPC 2.0 Protocol   │
│  • Game Management      │   │  • Tool Discovery           │
│  • Contains MCP Client  │   │  • 14 Chess Analysis Tools │
└─────────────────────────┘   └─────────────────────────────┘
              │                         │
              ▼                         ▼
┌─────────────────────────┐   ┌─────────────────────────────┐
│    Frontend (Svelte)    │   │    MCPServer Class          │
│  • Interactive Board    │   │  • analyze_position         │
│  • Stockfish Engine     │   │  • evaluate_move            │
│  • Game Replay          │   │  • get_best_moves           │
│  • Real-time Analysis   │   │  • explain_opening          │
└─────────────────────────┘   │  • validate_fen             │
                              │  • generate_pgn             │
                              │  • start_chess_ui           │
                              │  • stop_chess_ui            │
                              │  • start_chess_game         │
                              └─────────────────────────────┘

🔧 Configuration

Environment Variables

# Web Server Configuration
PORT=3456                                    # Server port
MCP_HOST_URL=http://localhost:3000/mcp/inbound  # MCP host endpoint
MCP_ENABLED=true                             # Enable/disable MCP integration
LOG_LEVEL=info                               # Logging level

# Development
NODE_ENV=development                         # Environment mode

Advanced Configuration

Local Development with Custom Path

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "node",
      "args": ["/path/to/stockfishmcp/bin/mcp"]
    }
  }
}

With Specific Version

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio", 
      "command": "npx",
      "args": ["[email protected]", "chess-trainer-mcp-server"]
    }
  }
}

Debug Mode

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "node",
      "args": ["--inspect", "/path/to/stockfishmcp/bin/mcp-server.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

⚠️ Troubleshooting

Common Issues

1. "Command not found" error

# Solution: Install the package
npm install -g chess-trainer-mcp

2. "JSON parsing errors" in MCP host

# Problem: Using wrong entry point
# ❌ Wrong: npx chess-trainer-mcp
# ✅ Correct: npx --package=chess-trainer-mcp chess-trainer-mcp-server

3. "Connection closed" or "MCP error -32000"

This usually indicates npm cache issues or version conflicts.

Quick Fix:

# Clear npm cache
npm cache clean --force

# Clear npx cache
rm -rf ~/.npm/_npx

# Use local path configuration (recommended for development)

Local Path Configuration (Most Reliable):

{
  "mcpServers": {
    "chess-trainer-mcp": {
      "transportType": "stdio",
      "command": "node",
      "args": ["/path/to/stockfishmcp/bin/mcp"],
      "cwd": "/path/to/stockfishmcp"
    }
  }
}

4. "No tools discovered"

• Check MCP configuration file format and path
• Ensure proper JSON syntax
• Restart MCP host application
• Verify server initialization with test command

5. "Connection timeout"

• Check network connectivity
• Verify npm package installation
• Try local path configuration
• Ensure no port conflicts

Testing MCP Server

Basic Connection Test

# Test if server responds (using npx)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx --package=chess-trainer-mcp chess-trainer-mcp-server

# Test using local path (if you have the source)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node /path/to/stockfishmcp/bin/mcp

# Should return: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}

Test Tool Discovery

# List all available tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node bin/mcp

# Should return 14 organized tools across 5 categories

Test Interactive Features

# Test listing active games
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_active_games","arguments":{}}}' | node bin/mcp

# Test position analysis
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"analyze_position","arguments":{"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"}}}' | node bin/mcp

🛠️ Development

Project Structure

stockfishmcp/
├── bin/
│   ├── chess-trainer-mcp      # Main CLI entry point (Web interface)
│   ├── mcp                    # Clean MCP entry point  
│   └── mcp-server.js          # MCP protocol implementation
├── client/                    # Frontend Svelte app
│   ├── src/components/        # Chess board, controls, etc.
│   ├── public/               # Stockfish WASM files
│   └── dist/                 # Built frontend
├── server/
│   ├── index.js              # Web server (ChessTrainerServer)
│   ├── mcpServer.js          # MCP tools implementation
│   └── mcpClient.js          # MCP client for outbound calls
└── package.json              # Defines both bin commands

Key Technologies

• Frontend: Svelte, Vite, Chessground, Chessops
• Chess Engine: Stockfish NNUE (WebAssembly)
• Backend: Node.js, Express, WebSocket
• Protocol: MCP (Model Context Protocol) JSON-RPC 2.0

Development Commands

npm run dev          # Start development server with hot reload
npm run build        # Build frontend for production
npm run setup        # Install all dependencies and build
npm start           # Start production server

📋 MCP Tools Reference

Server Management

launch_chess_trainer

Launch the Chess Trainer web server with optional browser opening.

{
  "name": "launch_chess_trainer",
  "arguments": {
    "port": 3456,
    "auto_open_browser": true
  }
}

stop_chess_trainer

Stop the Chess Trainer web server.

{
  "name": "stop_chess_trainer",
  "arguments": {
    "port": 3456
  }
}

Game Management

create_game

Create a new chess game with specific settings.

{
  "name": "create_game",
  "arguments": {
    "game_id": "my-game",
    "mode": "human_vs_ai",
    "player_color": "white",
    "ai_elo": 1500,
    "ai_time_limit": 1000
  }
}

list_active_games

List all currently active chess games.

{
  "name": "list_active_games",
  "arguments": {}
}

get_game_state

Get the current state of a specific chess game.

{
  "name": "get_game_state",
  "arguments": {
    "game_id": "my-game"
  }
}

reset_game

Reset a game to the starting position.

{
  "name": "reset_game",
  "arguments": {
    "game_id": "my-game"
  }
}

Game Interaction

make_move

Make a move in an active chess game.

{
  "name": "make_move",
  "arguments": {
    "game_id": "my-game",
    "move": "e2e4"
  }
}

suggest_best_move

Get the best move suggestion for the current position.

{
  "name": "suggest_best_move",
  "arguments": {
    "game_id": "my-game",
    "depth": 12
  }
}

Analysis Tools

analyze_position

Analyze a chess position (currently returns simulated analysis).

{
  "name": "analyze_position",
  "arguments": {
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "depth": 15
  }
}

evaluate_move

Evaluate the quality of a chess move.

{
  "name": "evaluate_move",
  "arguments": {
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "move": "e2e4"
  }
}

get_best_moves

Get the top N best moves for a position.

{
  "name": "get_best_moves",
  "arguments": {
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "count": 3
  }
}

Utility Tools

validate_fen

Validate a FEN string and get position information.

{
  "name": "validate_fen",
  "arguments": {
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
  }
}

generate_pgn

Generate PGN notation from a list of moves.

{
  "name": "generate_pgn",
  "arguments": {
    "moves": ["e4", "e5", "Nf3", "Nc6", "Bb5"],
    "white_player": "Magnus Carlsen",
    "black_player": "Hikaru Nakamura",
    "event": "Online Blitz",
    "date": "2025.06.27"
  }
}

explain_opening

Get explanation and principles of a chess opening.

{
  "name": "explain_opening",
  "arguments": {
    "moves": ["e4", "e5", "Nf3", "Nc6", "Bb5"],
    "opening_name": "Ruy Lopez"
  }
}

📝 Changelog

Version 1.1.0 (Latest)

• Upgraded to Svelte 5: Complete migration of the chess trainer client from Svelte 4 to Svelte 5
• Modern Component Syntax: Converted all components to use new Svelte 5 runes ($state, $props, $effect, $derived)
• Improved Event Handling: Migrated from createEventDispatcher to prop-based event system
• Better Performance: Leveraging Svelte 5's improved reactivity system and compiler optimizations
• Fixed Turn Tracking: Resolved issue where turns weren't updating correctly after moves
• Enhanced Type Safety: Better TypeScript support with Svelte 5's improved type inference

Version 1.0.11

• Reorganized MCP Tools: Streamlined from 16 to 15 tools with better categorization
• Improved Tool Names: Clearer, more descriptive tool names (e.g., suggest_move → suggest_best_move)
• Enhanced Server Startup: Better error handling and retry logic for launch_chess_trainer
• Added Proper Server Stop: New stop_chess_trainer tool that actually stops the server
• Game Persistence: Games now survive server restarts with automatic save/restore
• Auto-Save Feature: Games automatically saved every 30 seconds
• Inactive Game Cleanup: Games inactive for 24 hours are automatically archived
• Removed Redundant Tools: Eliminated confusing tools like start_chess_ui, stop_chess_ui, start_chess_game
• Added Tool Categories: Server Management, Game Management, Game Interaction, Analysis Tools, Utility Tools, Web Access Tools
• Fixed MCP SDK Integration: Resolved Zod schema issues for proper tool registration
• Updated Documentation: Comprehensive tool reference with examples

Version 1.0.10

• Major UI overhaul and feature enhancements
• Multi-client support with unique client identification
• Server-authoritative architecture implementation

📄 License

MIT License - see LICENSE file for details.

🤝 Support

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📚 Documentation: This README contains all configuration information

Ready to enhance your chess training with AI-powered analysis! 🚀♟️