Chess Mcp

chess-mcp

An MCP server that lets LLMs play chess in the macOS Chess app — two models take turns moving the real pieces on the actual Chess.app board, with a python-chess referee keeping every move legal.

> macOS only (built-in Chess app). Needs Python ≥ 3.12.

Install

python3 -m venv .venv && source .venv/bin/activate
python -m pip install -U pip && pip install -r requirements.txt

Play

1. Grant Accessibility permission to the terminal you'll run the server in:

System Settings → Privacy & Security → Accessibility → enable it → fully quit and reopen the terminal. (Required — the server presses real buttons.)

1. Start the server (leave it running):

``sh python -m chessmcp # serves http://127.0.0.1:8765/mcp `` Chess.app launches on its own — you don't need to open it.

1. Point your MCP client at it. Add this to the client's MCP config (for

Claude Code: claude mcp add --transport http chess http://localhost:8765/mcp): ``json { "mcpServers": { "chess": { "url": "http://localhost:8765/mcp" } } } ``

1. Tell the model: *"You're playing chess via the chess MCP server — call

join_game and follow its instructions."* It picks a color and plays the whole game on its own.

Two models against each other: start the one server, then point two clients (e.g. Claude Code and Codex) at the same URL and give each the line above. The server seats them on opposite colors automatically.

Just want to see it move pieces? Skip the client — this plays two random sides on the real board:

python selfplay.py --plies 20

Spoken narration (optional)

Have a voice call the moves and each model's reasoning aloud:

pip install -e '.[tts]'         # downloads a ~88MB voice model on first run
python -m chessmcp --narrate

Each side passes a short note in its move (e.g. "Grabbing the center early."); the narrator speaks the move plus that line, and the board waits for the voice so they never fall out of sync.

Troubleshooting

• "Accessibility permission not granted." Re-do step 1 — and make sure you

enabled the exact app running the server (your terminal), then fully quit and reopen it.

• Pieces won't move / a save dialog is stuck. Quit Chess.app (⌘Q, choose

Don't Save on any prompt) and start over.

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: janek-lopez
• Source: janek-lopez/chess-mcp
• License: MIT
• Homepage: https://medium.com/@janek.lopez/i-wanted-to-automate-my-mac-with-ai-but-ended-up-building-an-ai-chess-tournament-89a06431c31c

Install and usage instructions live in the source repository linked above.