@chessceo/mcp

Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts, cloud engine analysis, and (signed-in) a full read/write prep-file workflow. Lets Claude, Cursor, and any other MCP host answer chess questions directly against real data instead of hallucinating.

Player/game lookups need no API key or auth. Cloud engines and prep-file tools need a mcp_... bearer token (see Auth below).

What it can do

51 tools as of v0.49.3, mirroring the chess.ceo API surface. A few of the most-used:

| Tool | What it answers | |---|---| | search_player | "Find FIDE ID for Magnus Carlsen" | | get_player_profile | "How strong is X, what do they play, who have they beaten" | | prepare_opponent + get_prep_position | "What does X play against 1.e4? What's their win rate with the Najdorf?" | | get_position_stats | "From this position, which move scores best in the 11.7M-game database?" | | get_head_to_head | "What's the record between X and Y?" | | list_live_tournaments / list_tournament_players / list_player_live_tournaments | "What's being broadcast live right now? Who's playing? Is X in it?" | | cloud_analyse | "Run Stockfish + Lc0 on this position on my rented GPU instance" | | read_prep_file / add_line / add_move / apply_mutations | Read and edit your own repertoire/course PGNs stored server-side | | auto_evaluate / deep_analyse | Kick off a long-running engine-evaluation job over a whole prep file, poll it, cancel it | | read_docs | Bundled guides (engine usage, opening prep, prep-file conventions, PGN authoring, summary authoring) |

Full tool inventory with categories lives in CLAUDE.md under "Tools cheatsheet" — that's the maintained source of truth; this table is illustrative, not exhaustive.

Install (Claude Desktop)

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "chessceo": {
      "command": "npx",
      "args": ["-y", "@chessceo/mcp"]
    }
  }
}

Restart Claude Desktop. You should see the chess.ceo tools appear in the tool list at the bottom of the chat.

Install (Cursor)

Similar ~/.cursor/mcp.json:

{
  "mcpServers": {
    "chessceo": {
      "command": "npx",
      "args": ["-y", "@chessceo/mcp"]
    }
  }
}

Install (Claude Code)

This repo is also a Claude Code plugin marketplace, so you can add it directly:

/plugin marketplace add chessceo/chessceo-mcp
/plugin install chessceo@chessceo

Claude Code will pull the plugin from GitHub and wire the MCP server automatically. Enable "Sync automatically" in the marketplace UI if you want future updates fetched on push.

Auth (for cloud engines and prep files)

Read-only chess data — player search, profiles, position stats, head-to-head, live tournaments — needs nothing. Cloud engine tools and your own prep-file tools (list/read/create/edit) need a mcp_... bearer token.

• Local (npx/Claude Desktop/Cursor): set CHESSCEO_TOKEN in the server's env block:

  {
    "mcpServers": {
      "chessceo": {
        "command": "npx",
        "args": ["-y", "@chessceo/mcp"],
        "env": { "CHESSCEO_TOKEN": "mcp_..." }
      }
    }
  }

  Get a token from your chess.ceo account settings.
• Remote (mcp.chess.ceo/mcp): no config needed — calling an authed tool without a token triggers the host's normal OAuth flow (claude.ai, ChatGPT connectors) automatically.

Try it

Ask your model:

• "Who has the better record against Magnus Carlsen: Ding Liren or Fabiano Caruana?"
• "What does Alireza Firouzja play with White against the Najdorf?"
• "Are there any live tournaments right now with Hikaru Nakamura?"
• "From the position after 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6, what's the top continuation across the whole database?"

Prep workflow (built-in prompts)

For MCP hosts that show prompts in a slash-menu (Claude Desktop, Cursor, Claude Code), three pre-baked prompts are included so users get a proper preparation workflow without prompt-engineering their own:

| Prompt | Purpose | |---|---| | prepare_for_game(me, opponent, my_color?, time_control?) | Full pre-match workflow: resolves both players, weights games by recency + format (classical OTB > rapid/blitz > online), walks the opponent's repertoire looking for lines where they score under 40%, checks head-to-head, and delivers a concrete plan with the moves to steer toward the opponent's weak points. | | scout_player(player) | Deep scouting report on one player — style, top openings, recent form, biggest wins and losses, recurring weaknesses. | | head_to_head_briefing(player_a, player_b) | One-paragraph read on the history between two players — who has the edge, dominant openings, style clash, current form. |

Pick one from the host's slash-menu, fill in the arguments, and the model does the rest.

Remote MCP (chess.ceo-hosted)

You can also connect to chess.ceo's hosted instance and skip installing anything:

https://mcp.chess.ceo/mcp

In Claude Code:

/plugin add-mcp url https://mcp.chess.ceo/mcp

In Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "chessceo": {
      "url": "https://mcp.chess.ceo/mcp"
    }
  }
}

Same tools, same data, zero-install. Bearer-authed tools (cloud engines, prep files) go through this host's OAuth flow instead of a config-file token. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).

Self-host the HTTP transport

The same package can run as a persistent HTTP server, not just a stdio subprocess:

chessceo-mcp --transport=http --http-port=8080 --http-host=127.0.0.1

Flags (or the corresponding env vars):

| Flag | Env var | Default | Purpose | |---|---|---|---| | --transport | MCP_TRANSPORT | stdio | stdio or http | | --http-port | MCP_HTTP_PORT | 8080 | Port to bind | | --http-host | MCP_HTTP_HOST | 127.0.0.1 | Bind address | | --http-path | MCP_HTTP_PATH | /mcp | Streamable-HTTP endpoint |

GET /healthz returns 200 ok\n — wire it into your uptime monitor.

systemd unit (example)

# /etc/systemd/system/chessceo-mcp.service
[Unit]
Description=chess.ceo MCP server (Streamable HTTP)
After=network.target

[Service]
Type=simple
User=www-data
Environment=NODE_ENV=production
Environment=MCP_TRANSPORT=http
Environment=MCP_HTTP_PORT=8127
Environment=MCP_HTTP_HOST=127.0.0.1
ExecStart=/usr/bin/npx -y @chessceo/mcp
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

nginx snippet (example)

server {
    listen 443 ssl http2;
    server_name mcp.chess.ceo;

    ssl_certificate     /etc/letsencrypt/live/mcp.chess.ceo/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.chess.ceo/privkey.pem;

    # Streamable HTTP is short JSON POSTs — no long-poll SSE required.
    location /mcp {
        proxy_pass         http://127.0.0.1:8127/mcp;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_buffering    off;   # streaming responses shouldn't be buffered
        proxy_read_timeout 300s;
    }

    location = /healthz { proxy_pass http://127.0.0.1:8127/healthz; }
}

Development

git clone <this repo>
cd chessceo-mcp
npm install
npm run build   # tsc → dist/
npm start       # runs the server on stdio (for MCP hosts)

# or run the HTTP transport locally:
node dist/index.js --transport=http --http-port=8127
curl http://127.0.0.1:8127/healthz     # should print "ok"

Environment variable overrides:

• CHESSCEO_BASE_URL — override the API base (default https://chess.ceo). Useful for testing against staging.
• MCP transport env vars — see the self-host table above.

What's under the hood

The chess.ceo public API is a GET-only surface documented at chess.ceo/llms.txt. This MCP server is a thin wrapper — one tool per endpoint, with input schemas so LLMs can call them safely. When you ask the model a chess question, it picks the right tool, calls it, and reasons over the JSON. Nothing is invented; the data is straight from the database.

License

MIT