# Chess Mcp

> Let LLMs play chess on the real macOS Chess.app, an MCP server driving it through the Accessibility API.

- **Type:** MCP server
- **Install:** `agentstack add mcp-janek-lopez-chess-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [janek-lopez](https://agentstack.voostack.com/s/janek-lopez)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [janek-lopez](https://github.com/janek-lopez)
- **Source:** https://github.com/janek-lopez/chess-mcp
- **Website:** https://medium.com/@janek.lopez/i-wanted-to-automate-my-mac-with-ai-but-ended-up-building-an-ai-chess-tournament-89a06431c31c

## Install

```sh
agentstack add mcp-janek-lopez-chess-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](https://python-chess.readthedocs.io) referee keeping every move
legal.

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

## Install

```sh
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.)

2. **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.

3. **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" } } }
   ```

4. **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:

```sh
python selfplay.py --plies 20
```

## Spoken narration (optional)

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

```sh
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](https://github.com/janek-lopez)
- **Source:** [janek-lopez/chess-mcp](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-janek-lopez-chess-mcp
- Seller: https://agentstack.voostack.com/s/janek-lopez
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.