secret-hitler-mcp
# Secret Hitler MCP and model arena
A small experiment in connecting AI models to a board game.
- An **MCP server** lets any MCP-capable model take one seat in
[Secret Hitler Online](https://github.com/ShrimpCryptid/Secret-Hitler-Online), alongside humans in the browser.
- An **arena runner** plays whole games on a local server with a different model in every seat, records
every move, and shows a live spectator page.
- **[RESULTS.md](RESULTS.md)** describes 40 recorded games between five free-tier models. The game records
are in [`data/`](data/).
## The game
Secret Hitler is a hidden-role game. With 5 players there are 3 Liberals, 1 Fascist and Hitler. The Fascist
and Hitler know each other; the Liberals know nothing. Each round a President nominates a Chancellor, everyone
votes, and an elected pair enacts one policy from a deck of 11 Fascist and 6 Liberal cards. Liberals win with 5
Liberal policies or by executing Hitler. Fascists win with 6 Fascist policies, or by getting Hitler elected
Chancellor once 3 Fascist policies are down.
## Setup
Requires Python 3.11+ and Docker.
```bash
# The game server, in its own clone
git clone https://github.com/ShrimpCryptid/Secret-Hitler-Online.git
cd Secret-Hitler-Online
docker compose up -d db backend # add frontend to play in a browser at :3000
# This project
cd ../secret-hitler-mcp-arena
python -m venv .venv
.venv/Scripts/pip install -e . # Linux/macOS: .venv/bin/pip
python -m unittest discover tests
```
## One model in a game with humans (MCP)
Claude Code: `claude mcp add secret-hitler -- secret-hitler-mcp`. Other MCP clients can run `secret-hitler-mcp`
as a stdio server. Create a lobby in the browser, then ask the model to use the `play_secret_hitler` prompt
with your lobby code and a player name.
| Tool | When |
|---|---|
| `join_lobby(lobby_code, player_name, server_url)` | Once |
| `start_game()` | Host only |
| `get_game_state()`, `get_game_log()` | Any time |
| `wait_for_my_turn(timeout_seconds)` | Between moves |
| `nominate_chancellor(player)` | President |
| `vote(ja)` | Everyone alive |
| `president_discard(card_index)`, `chancellor_enact(card_index)` | Legislative session |
| `propose_veto()`, `respond_to_veto(accept)` | After 5 Fascist policies |
| `use_power(target)` | Investigate, execute or special election |
| `finish_turn()` | Acknowledge a peek or end a term |
`view.py` exposes only what the rules let that seat know, even when the server sends more. The `debug_*` tools
bypass this, so remove them from the model's tool list during real games.
## Models against each other (arena)
The arena does not use MCP. It talks to the game server directly, through the same protocol and rules code, so
every model gets the same prompt, the same information and the same move format.
```bash
# Set keys in your shell, never in files: GROQ_API_KEY and GEMINI_API_KEY
python -m secret_hitler_mcp.arena.run --config arena-free.toml --check
python -m secret_hitler_mcp.arena.run --config arena-free.toml --games 20 -v
python -m secret_hitler_mcp.arena.results logs/arena/run-<timestamp>
```
The live spectator page is at http://localhost:4042. If a daily limit stops a run during game N, continue later
with `--start-at N --games <21 - N>`. To use your own lineup, copy `arena.example.toml` to `arena.toml`.
`--evidence` gives Liberal seats per-player policy counts computed from the public history, and writes to
`logs/arena-evidence`. To reproduce the numbers in RESULTS.md:
```bash
python tools/analyse_results.py data/baseline data/evidence
```
`tools/probe_models.py` checks whether a provider and model answer a real request.
## Fair play
- Use the AI as its own seat that everyone knows about, rather than secretly piloting your own seat.
- Don't point bots at the public server without the maintainer's okay. Run the arena on your own server.
## Credit and license
Built for [Secret Hitler Online](https://github.com/ShrimpCryptid/Secret-Hitler-Online) by ShrimpCryptid, which
adapts the original board game by Goat, Wolf & Cabbage. This project is released under
[CC BY-NC-SA 4.0](LICENSE), the same license as both, so it is for non-commercial use only. It is not affiliated
with or endorsed by either.
TDQS
Scored across 14 tools
Each tool maps to a distinct game phase or role action (nominate, vote, president_discard, chancellor_enact, veto propose/respond, use_power), so an agent reading get_game_state can unambiguously pick the required tool. The two potentially confusable pairs (president_discard vs chancellor_enact, propose_veto vs respond_to_veto) are explicitly differentiated by role in their descriptions.
All names use snake_case and are readable, with most following a verb_noun pattern (join_lobby, nominate_chancellor, respond_to_veto, finish_turn). Two outliers invert the order to a noun_verb role prefix (chancellor_enact, president_discard), a minor deviation from the otherwise predictable convention.
Fourteen tools is well within the sweet spot and each corresponds to a real action in the Secret Hitler turn cycle. No tool feels redundant or padded; use_power sensibly bundles the three executive powers into one call rather than inflating the count.
The surface covers the full gameplay lifecycle: lobby join/rejoin, game start, state and log reads, every role action, veto flow, executive powers, and turn advancement, with wait_for_my_turn preventing dead ends. Minor gaps remain (no explicit leave/abort lobby or in-game chat/table-talk tool), but these are workable around.