ChessMovio ChessMovio

AI Integration

Connect Claude, Codex, and other AI assistants to ChessMovio via MCP

ChessMovio includes a built-in MCP (Model Context Protocol) server that lets AI assistants read and annotate the game currently open in the Game Viewer. This means you can have a conversation with Claude or Codex about your chess game, and the AI can see the position, add comments, draw arrows, and navigate through moves -- all in real time.

macOS only: The MCP server is available on macOS only. It requires a Premium subscription.

What Is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external tools and data sources. ChessMovio runs a local MCP server on your Mac that exposes your current game as a set of tools the AI can use.

When connected, the AI assistant can:

  • Read the current board position, game metadata, move list, and annotations
  • Analyze positions using ChessMovio's built-in Stockfish engine
  • Write comments, NAG symbols (!, ?, !!, ??, !?, ?!), and board drawings (arrows and colored squares)
  • Navigate through the game by moving to specific plies or variation nodes

Enabling the MCP Server

  1. Open ChessMovio on macOS.
  2. Go to Settings > AI Integration.
  3. Toggle Enable MCP Server.
  4. Note the port number (default: 8421). You can change it if another application is using that port.

The status indicator shows whether the server is running. The server binds to localhost only, so it is not accessible from other machines on your network.

Configuring Claude Desktop

Claude Desktop connects to ChessMovio through mcp-remote, a bridge that translates between Claude's stdio transport and ChessMovio's HTTP server.

Prerequisites

  • Node.js must be installed on your Mac (for the npx command). You can install it from nodejs.org or via Homebrew: brew install node.
  • Claude Desktop must be installed. Download it from claude.ai/download.

Setup

  1. In ChessMovio, go to Settings > AI Integration and click Copy Config. This copies a JSON snippet to your clipboard.
  2. In Claude Desktop, go to Settings > Developer > Edit Config.
  3. Paste the copied JSON into the config file. If the file already has content, merge the mcpServers entries.
  4. Save the file and restart Claude Desktop.

The config looks like this:

{
  "mcpServers": {
    "chessmovio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8421/mcp"]
    }
  }
}

After restarting Claude Desktop, you should see ChessMovio listed as a connected MCP server. Open a game in ChessMovio's Game Viewer, then ask Claude something like "What opening is this game?" or "Add comments to the first 10 moves explaining the ideas."

Configuring Claude Code

Claude Code uses the same MCP configuration format. Add the ChessMovio server to your project or global settings.

Setup

  1. In ChessMovio, go to Settings > AI Integration and click Copy Config.
  2. Open your Claude Code MCP settings file (.claude/settings.json in your project directory, or the global settings).
  3. Paste the copied JSON, merging mcpServers if there are existing entries.

Alternatively, use the Claude Code CLI:

claude mcp add chessmovio -- npx -y mcp-remote http://localhost:8421/mcp

Once configured, Claude Code can access your ChessMovio game data during any conversation. Open a game in ChessMovio, then ask Claude Code to analyze it, annotate moves, or review your play.

Configuring Codex

OpenAI Codex and other MCP-compatible clients can connect to ChessMovio's MCP server directly.

Setup

Any MCP client that supports the Streamable HTTP transport can connect to:

http://localhost:8421/mcp

For clients that only support stdio transport (like Codex CLI), use mcp-remote as a bridge:

npx -y mcp-remote http://localhost:8421/mcp

Consult your client's documentation for how to add a custom MCP server.

What the AI Can Do

Once connected, the AI assistant has full access to the game open in your Game Viewer. Here is what it can see and do:

Reading Your Game

  • Board position -- The AI sees the current position on the board, including whose turn it is, the move number, and whether you are in the mainline or a variation.
  • Game information -- Player names, ratings, event, date, result, ECO code, opening name, and the full move list.
  • Move details -- Every move in the game with any existing comments, symbols, and classifications (blunders, mistakes, inaccuracies).
  • Annotations -- Comments, evaluation symbols (!, ?, !!, etc.), arrows, colored squares, and bookmarks on any move.
  • Engine analysis -- If the Stockfish engine is running, the AI can request an evaluation of the current position and get the engine's recommended line.

Annotating Your Game

  • Comments -- The AI can add or replace text comments on any move, explaining ideas, plans, or mistakes.
  • Evaluation symbols -- It can mark moves with standard chess symbols like !, ?, !!, ??, !?, and ?!.
  • Board drawings -- It can draw arrows and highlight squares on the board in green, red, blue, or yellow to illustrate tactical and positional ideas.
  • Navigation -- It can move through the game to any position, and the board updates in real time as it does so.
  • Cleanup -- It can remove specific annotations (comments, symbols, drawings, or bookmarks) from any move.

Example Conversations

Here are some things you can ask an AI assistant once connected:

  • "Look at the current game and tell me about the opening. What are the key ideas for both sides?"
  • "Go through the first 10 moves and add brief comments explaining the opening plans."
  • "Find the most critical moments in this game and mark them with arrows showing the key moves."
  • "What is the engine evaluation of this position? Is there a tactic here?"
  • "Review my annotations on move 15 and suggest improvements."

Troubleshooting

Server won't start

  • Make sure the MCP server toggle is enabled in Settings > AI Integration.
  • Check that the port is not already in use by another application. Try changing it to a different number.
  • Verify that you have an active Premium subscription.

Claude Desktop doesn't see ChessMovio

  • Restart Claude Desktop after editing the config file.
  • Make sure Node.js is installed (node --version in Terminal).
  • Check that ChessMovio is running and the MCP server status shows Running.
  • Verify the port in the config matches the port shown in ChessMovio settings.

"No game is open" error

The AI needs a game to be open in the Game Viewer before it can read or annotate anything. Open a game from My Games, Reference Games, or any other source first.

Engine evaluation not available

Engine analysis requires the Stockfish engine to be running. Start the engine by clicking the CPU icon in the Game Viewer toolbar before asking the AI for an evaluation.