Skip to main content
Glama
Sign In
secret-hitler-mcp

secret-hitler-mcp

by pranavshenvi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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, 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 describes 40 recorded games between five free-tier models. The game records are in 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.

Related MCP server: a2a-raid-mcp

Setup

Requires Python 3.11+ and Docker.

# 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.

# 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:

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 by ShrimpCryptid, which adapts the original board game by Goat, Wolf & Cabbage. This project is released under CC BY-NC-SA 4.0, the same license as both, so it is for non-commercial use only. It is not affiliated with or endorsed by either.

Available Tools

14 tools
chancellor_enactB

As Chancellor, ENACT the card at this 0-based index (the other is discarded).

Inputs: card_index (required).

finish_turnB

As President, acknowledge a policy peek or end your term when the game asks you to continue.

Inputs: no named parameters.

get_game_logA

History of elections, votes, enacted policies and executions, plus your private info (cards you saw, investigations).

Inputs: no named parameters.

get_game_stateB

Your current view: role, known teammates, board, phase, and whether anything is required of you ('your_turn').

Inputs: no named parameters.

join_lobbyA

Join an existing lobby as a player (or rejoin a game you were disconnected from). The host creates the lobby in the browser and shares the code. lobby_code may also be a full invite link (e.g. https://secret-hitler.online/?lobby=ABCD); server_url may be the public website, which is mapped to its game backend.

Inputs: lobby_code (required), player_name (required), server_url.

nominate_chancellorB

As President, nominate a Chancellor from the eligible options.

Inputs: player (required).

post_noteA

Show one short line of your reasoning on the human's local viewer page (http://localhost:4041). Use it after reading the state and before each move. Only the human running this MCP server sees it, never the other players.

Inputs: text (required).

president_discardA

As President, discard one of the 3 drawn policy cards (0-based index). The rest go to the Chancellor.

Inputs: card_index (required).

propose_vetoA

As Chancellor with 5 fascist policies on the board, propose vetoing this hand.

Inputs: no named parameters.

respond_to_vetoB

As President, accept or reject the Chancellor's veto proposal.

Inputs: accept (required).

start_gameA

Start the game (any player in the lobby can; needs 5-10 players, all with icons).

Inputs: no named parameters.

use_powerB

As President, use the current executive power (investigate / execute / special_election) on a player.

Inputs: target (required).

voteB

Vote on the proposed government. ja=True for Ja (yes), False for Nein.

Inputs: ja (required).

wait_for_my_turnA

Block until the server needs an action from you (or the game ends). Call this in a loop between moves.

Inputs: timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • gap

      lonexreb
      A
      license
      A
      quality
      C
      maintenance
      Enables any local AI agent to play turn-based games over MCP by exposing reset, observe, and act verbs with structured observations and validated legal actions.
      6
      1
      MIT

    • a2a-raid-mcp

      alvintayzhenwei
      A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to connect to and play a seat in the Agent Raid co-op boss-raid A2A game, using MCP tools to wait for turns, submit moves, and exchange party chat.
      7
      52 PyPI
      1
      MIT

    • HexSet MCP Server

      0xBrsm
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables programmatic interaction with HexSet's Catan rules engine, including game management, legal actions, and bot opponents through MCP tools.
      GPL 3.0

    • rain-go

      SerenQi
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI and humans to play 10 board, card, and dice games together via MCP tools, with seat-based multiplayer and server-side hidden-hand isolation.
      21
      MIT