How do I use Chess MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Chess MCP Let's play chess! I'll start with e4" 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.

Chess MCP App

A ChatGPT Chess application built with OpenAI Apps SDK, allowing you to play chess through conversation with an interactive board widget.

Now following OpenAI Apps SDK best practices!

Features

🎮 Play chess using algebraic notation (e4, Nf3, O-O, etc.)
📊 Interactive chess board widget in ChatGPT
🤖 AI opponent suggestions (ChatGPT can play moves)
🔍 Stockfish engine analysis integration
📝 Move history tracking
✅ Full move validation and game state management
📋 Game status and player information display
🧩 Mate in 1 tactical puzzles (Easy, Medium, Hard)

Architecture

Backend: Python MCP Server using FastMCP with python-chess
Frontend: React component with chess.js + react-chessboard
Build System: Vite for optimal development experience
Integration: OpenAI Apps SDK patterns with proper hooks

Project Structure

ChessMCP/
├── server/
│   ├── main.py              # Python MCP server (renamed from server.py)
│   └── requirements.txt     # Python dependencies
├── src/
│   ├── chess-board/         # Chess board component
│   │   └── index.tsx
│   ├── types.ts             # Shared TypeScript types
│   ├── use-openai-global.ts # Hook for window.openai access
│   ├── use-widget-state.ts  # Hook for widget state
│   └── use-widget-props.ts  # Hook for tool props
├── assets/                  # Build output (generated by Vite)
│   └── chess-board.html
├── vite.config.mts          # Vite configuration
├── package.json             # Root dependencies
├── tsconfig.json            # TypeScript config
└── README.md

Installation

Prerequisites

Python 3.8+
Node.js 18+
Stockfish chess engine (optional, for analysis)

Setup Steps

Install Python dependencies:

cd server
pip3 install -r requirements.txt

Install Stockfish (optional, for engine analysis):

# macOS
brew install stockfish

# Ubuntu/Debian
sudo apt-get install stockfish

Install Node.js dependencies:

npm install

Build the frontend component:

npm run build

This generates assets/chess-board.html which the server loads.

The MCP server is configured in your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "chess": {
      "command": "python3",
      "args": ["/path/to/ChessMCP/server/main.py"],
      "env": {
        "PYTHONPATH": "/path/to/ChessMCP/server"
      }
    }
  }
}

Development Workflow

Build Once (Production)

npm run build

Development Mode (with hot reload)

# Terminal 1: Start Vite dev server
npm run dev

# Terminal 2: Start Python server
cd server
python3 main.py

Serve Built Assets (for testing)

npm run serve

Testing Locally (No ChatGPT Required!)

Option 1: Direct Local Tester (Recommended)

Play chess directly without server/OAuth:

python3 chess_local_test.py

Commands:

♟️  > move e4
♟️  > move e5
♟️  > status
♟️  > stockfish
♟️  > puzzle medium

📖 See: LOCAL_TESTING.md

Option 2: HTTP Client

Test via HTTP (requires server running):

# Terminal 1: Start server
cd server && python3 main.py

# Terminal 2: Start client
python3 chess_client.py

📖 See: CLIENT_USAGE.md

Testing with ChatGPT

The Chess MCP server now includes Google OAuth 2.1 authentication for secure ChatGPT integration!

📖 Quick Start: OAUTH_QUICK_START.md (5 minutes)
📖 Detailed Setup: GOOGLE_OAUTH_SETUP.md (Step-by-step)
📖 Next Steps: NEXT_STEPS.md (What to do now)
📖 Troubleshooting: CHATGPT_CONNECTOR_TROUBLESHOOTING.md

Quick start:

# 1. Set up Google OAuth credentials (see GOOGLE_OAUTH_SETUP.md)
# 2. Create server/.env with credentials

# Terminal 1: Start server
cd server
pip3 install -r requirements.txt
python3 main.py

# Terminal 2: Expose with ngrok
ngrok http 8000

# Update server/.env with ngrok URL, restart server

# Then add connector in ChatGPT Settings > Connectors
# URL format: https://YOUR-SUBDOMAIN.ngrok-free.app (no /mcp suffix)

Usage

Starting a Game

In ChatGPT, start a chess game by making your first move:

ChessMCP e4

Let's play chess! I'll start with e4

The interactive chess board will appear showing your move.

Making Moves

Simply type your move in algebraic notation:

Nf3
e5
Bc4
Nc6

Supported notation:

Basic moves: e4, Nf3, d5
Captures: exd5, Nxf7
Castling: O-O (kingside), O-O-O (queenside)
Pawn promotion: e8=Q, a1=N
Check: Qh5+
Checkmate: Qf7#

Additional Commands

Check game status:

chess_status
What's the current status?

Load a puzzle:

Show me a chess puzzle
Give me a hard puzzle

Get engine analysis:

Ask Stockfish for the best move

Reset game:

chess_reset
Let's start a new game

MCP Tools

The server exposes five tools:

`chess_move`

Input: move (string) - Algebraic notation
Output: Updated board state with FEN, move history, game status
Widget: Renders interactive chess board

`chess_stockfish`

Input: depth (int, default: 15) - Analysis depth
Output: Best move, evaluation, principal variation
Widget Accessible: Can be called from the widget UI

`chess_reset`

Input: None
Output: Confirmation of reset
Widget: Shows fresh starting position

`chess_status` ⭐

Input: None
Output: Game status, current turn, player names, move count, recent moves
Use: Check game progress and who's moving

`chess_puzzle` ⭐

Input: difficulty (string: "easy", "medium", "hard")
Output: Mate-in-1 puzzle position with hint
Widget: Shows puzzle position on the board
Use: Practice tactical patterns and checkmate recognition

React Hooks (Apps SDK Patterns)

The component uses OpenAI Apps SDK hooks for clean, reactive code:

`useOpenAiGlobal(key)`

Access window.openai properties reactively:

const theme = useOpenAiGlobal("theme");
const displayMode = useOpenAiGlobal("displayMode");

`useToolOutput<T>()`

Get the current tool output:

const toolOutput = useToolOutput<ChessToolOutput>();
// Returns: { fen, move, status, turn }

`useToolResponseMetadata<T>()`

Get tool response metadata:

const metadata = useToolResponseMetadata<ChessMetadata>();
// Returns: { move_history_list, legal_moves, etc. }

`useWidgetState<T>(defaultState)`

Persist component state across sessions:

const [widgetState, setWidgetState] = useWidgetState<ChessWidgetState>({
  lastDepth: 15,
  analysisVisible: false
});

Build System (Vite)

Why Vite?

⚡️ Fast hot module replacement during development
📦 Optimized production builds
🎯 TypeScript support out of the box
🔧 Better error messages
🎨 Source maps for debugging

Build Output

The build creates a single HTML file containing:

Bundled React component
All JavaScript dependencies
Inline CSS
Proper structure for Skybridge runtime

Configuration

See vite.config.mts for the build configuration. The setup:

Bundles src/chess-board/index.tsx
Includes all dependencies
Wraps in HTML with proper structure
Outputs to assets/chess-board.html

Server Architecture

Resource Handling

The server follows Apps SDK patterns:

# Load HTML from assets
@lru_cache(maxsize=None)
def load_widget_html(component_name: str) -> str:
    html_path = ASSETS_DIR / f"{component_name}.html"
    return html_path.read_text(encoding="utf8")

# Proper MIME type
MIME_TYPE = "text/html+skybridge"

# Resource registration
@mcp._mcp_server.list_resources()
async def list_resources() -> List[types.Resource]:
    return [types.Resource(...)]

# Resource handler
async def handle_read_resource(req) -> types.ServerResult:
    html = load_widget_html("chess-board")
    return types.ServerResult(types.ReadResourceResult(...))

Tool Metadata

All tools include proper metadata:

{
    "openai/outputTemplate": "ui://widget/chess-board.html",
    "openai/widgetAccessible": True,
    "openai/resultCanProduceWidget": True,
    "openai/toolInvocation/invoking": "Making move...",
    "openai/toolInvocation/invoked": "Move played"
}

Troubleshooting

Ensure component is built: npm run build
Verify assets/chess-board.html exists
Check server logs for errors

Stockfish Not Found

Update the path in server/main.py:

STOCKFISH_PATH = "/path/to/stockfish"

Build Errors

If TypeScript errors occur:

npm run typecheck

Server Won't Start

Make sure all Python dependencies are installed:

cd server
pip3 install -r requirements.txt

What's New in This Version

✨ Restructured Project

Moved from web/ to src/ directory
Root-level package.json and vite.config.mts
Proper Apps SDK project structure

🎣 React Hooks

useOpenAiGlobal for reactive window.openai access
useWidgetState for persistent state management
useToolOutput and useToolResponseMetadata for props

⚡ Vite Build System

Replaced esbuild with Vite
Hot module replacement in development
Better TypeScript support
Faster builds

🏗️ Server Improvements

Proper resource loading from assets/
Correct MIME type (text/html+skybridge)
Better error handling
CORS middleware for development

📝 Better Types

Comprehensive TypeScript types
Apps SDK-compatible interfaces
Chess-specific type definitions

Contributing

Feel free to enhance the app with:

Opening analysis and endgame tablebases
Multiple game sessions
PGN import/export
Time controls
Online multiplayer
More puzzle types

License

MIT License - feel free to use and modify!