# Game Master Mcp

> Really play board games with your AI — an MCP game server with six rule-enforcing engines and a cozy local web Game Room

- **Type:** MCP server
- **Install:** `agentstack add mcp-theferalcode-pixel-game-master-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [theferalcode-pixel](https://agentstack.voostack.com/s/theferalcode-pixel)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [theferalcode-pixel](https://github.com/theferalcode-pixel)
- **Source:** https://github.com/theferalcode-pixel/game-master-mcp

## Install

```sh
agentstack add mcp-theferalcode-pixel-game-master-mcp
```

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

## About

# Game Master

**Really play board games with your AI.** Not "describe a board and hope" — a
tiny local game server keeps the actual state, enforces the actual rules, and
lets both of you make real moves: your AI through [MCP](https://modelcontextprotocol.io)
tools, you in conversation or in a cozy little web Game Room.

Six games, complete rules, no honor system:

| Game | The rules it enforces |
| --- | --- |
| **Tic-tac-toe** | The quick classic |
| **Connect Four** | Gravity, four in a row |
| **Checkers** | Mandatory captures, multi-jumps, kinging |
| **Backgammon** | Blots, the bar, bearing off, doubles |
| **Chess** | Castling, en passant, promotion, check, checkmate, stalemate, fifty-move rule, threefold repetition, insufficient material |
| **Battleship** | Two hidden 10×10 fleets — each side only ever sees its own ships and its own shot results. The secrets stay on the server. |

Finished matches land in a **house ledger** automatically (wins, streaks,
longest game), and your AI gets a tool to decorate each match with a title and
a postgame note. The web lobby displays the ledger under the game shelf,
next to a tiny trophy cabinet.

## Quick start — the MCP server

Requires Python 3.10+ and the `mcp` package:

```bash
pip install mcp
```

Then register `game_master.py` with your MCP client.

**Claude Code:**

```bash
claude mcp add game-master -- python3 /path/to/game-master-mcp/game_master.py
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "game-master": {
      "command": "python3",
      "args": ["/path/to/game-master-mcp/game_master.py"]
    }
  }
}
```

Any other MCP client works the same way: it's a plain stdio server.

Now ask your AI to start a game ("new chess game — you're Black"). The two
seats are always called `human` and `agent`; your AI plays as `agent`. Game
state lives in `~/.game-master/games/` (override with `GAME_MASTER_HOME`).

## The web Game Room (optional but lovely)

```bash
python3 server.py        # or: ./ctl.sh start
```

Open http://127.0.0.1:8777/ — a lamp-lit room with the six game boxes on a
shelf and the house ledger below. Click a box to sit down: the board is on the
left, the rules card and (optionally) your AI's chat seat on the right. The
browser plays as `human` at dedicated tables (`room-chess`, `room-battleship`,
…), so games you play purely in conversation are never disturbed.

The board polls the same state files the MCP tools write, so when your AI
takes its turn — from any client — the move appears on your screen.

### Make it yours

Copy `config.example.json` to `config.json` (or use environment variables):

```json
{
  "player_name": "Sam",
  "agent_name": "Aria",
  "theme": "hearth"
}
```

- **Names** appear everywhere: turn notes, the chat seat, the ledger.
- **Themes**: `hearth` (warm amber wood), `tide` (deep ocean blues),
  `grove` (forest greens). There's a picker in the lobby too.

### The chat seat

If your AI setup exposes a local chat server speaking the Hermes WebUI chat
API (`/api/session/new`, `/api/chat/start`, SSE `/api/chat/stream`), set
`chat_url` (e.g. `http://127.0.0.1:8787`) and the Game Room embeds a live
chat panel beside every board — trash talk and "your move" nudges included.

Without it, the chat seat politely explains it's not wired up, and everything
else works exactly the same: you click, your AI plays through its tools, the
board updates.

## How honesty works

- **Nothing performs a move for you.** The browser only acts on your explicit
  clicks; the AI only acts through its tools; the server rejects anything
  illegal, out of turn, or out of bounds.
- **Battleship never leaks.** Fleets exist only in the server's state files.
  Both the browser view and the AI's `battleship_get_state` tool return a
  redacted view: your own fleet, plus hit/miss/sunk marks for your shots.
- **The ledger records itself.** When a game ends, the result is written with
  a `record_id`; the AI's `gameroom_annotate_match` tool adds the flavor.

## Development

```bash
pip install mcp pytest
python -m pytest tests/
```

`game_master.py` holds all six engines plus the MCP tool definitions;
`server.py` is a dependency-free stdlib web server; `web/` is plain
HTML/CSS/JS, no build step.

## 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:** [theferalcode-pixel](https://github.com/theferalcode-pixel)
- **Source:** [theferalcode-pixel/game-master-mcp](https://github.com/theferalcode-pixel/game-master-mcp)
- **License:** MIT

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-theferalcode-pixel-game-master-mcp
- Seller: https://agentstack.voostack.com/s/theferalcode-pixel
- 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%.