poker-mcp

A poker study / decision-support MCP server and multi-table simulator. It lets an MCP client (Cursor, Claude Desktop, etc.) spin up simulated No-Limit Texas Hold'em tables, play against simple opponent bots across multiple tables at once, and get equity / pot-odds / preflop-chart-based advice for study and practice.

Built on:

• mcp — the official Python MCP SDK (FastMCP, stdio transport).
• pokerkit — poker game engine and hand evaluation (NoLimitTexasHoldem, StandardHighHand).
• pydantic — typed tool inputs/outputs.

Scope & non-goals (please read)

This is a study and simulation tool, not a cheating tool.

• No real-money site automation or scraping. It does not connect to, scrape, read the screen of, or automate any commercial/real-money poker client. It only plays its own self-contained simulated tables.
• No webcam / computer-vision player reads. Opponent "reads" here are purely statistics derived from hands you simulate or explicitly import. (A future, clearly-opt-in stub is mentioned below but is out of scope for v1.)
• No GTO solver in v1. Advice is heuristic (Monte Carlo equity + pot odds + simple preflop ranges). Real solver integration is a future phase (see Roadmap).

Use it to practice multi-tabling, sanity-check equities, and rehearse decisions — not to gain an unfair edge in real games.

Features

• Multi-table NLHE simulator with configurable blinds, stacks, seats, and hero seat.
• Opponent bots: RandomBot, TightBot, CallingStationBot (and a mixed profile).
• get_pending_actions() multi-table driver: find every table waiting on you.
• Monte Carlo equity vs N random opponents, plus pot-odds helper.
• Simple JSON preflop range charts (ships with a 6-max RFI chart).
• Heuristic advise() combining equity + pot odds + preflop chart with EV rationale.
• SQLite hand-history storage and opponent stats (VPIP / PFR / AF).

Install

Requires Python >= 3.11 and uv.

uv sync            # create .venv and install runtime deps
uv sync --extra dev  # also install dev deps (pytest)

Run

# as a module
uv run python -m poker_mcp.server

# or via the console script
uv run poker-mcp

The server speaks the MCP stdio transport, so it's normally launched by an MCP client rather than used interactively.

Register in Cursor / Claude (stdio)

Add an entry to your MCP config (e.g. .cursor/mcp.json or Claude Desktop's claude_desktop_config.json). Point cwd at this repository so uv resolves the project environment:

{
  "mcpServers": {
    "poker-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "poker_mcp.server"],
      "cwd": "/Users/vedsm/projects/poker-mcp"
    }
  }
}

Tools

Tool	Description
create_table(seats, small_blind, big_blind, starting_stack, hero_seat, bot_profile)	Create a table and deal the first hand; auto-advances bots to the hero.
list_tables()	Summaries of all open tables.
close_table(table_id)	Close/remove a table.
get_table_state(table_id)	Full state summary (board, pot, stacks, hero cards, whose turn, street).
get_legal_actions(table_id)	Legal betting actions for the current actor.
get_pending_actions()	Every table currently waiting on the hero (multi-table driver).
submit_action(table_id, action, amount)	Apply the hero's action, then auto-advance bots to the next decision.
autoplay_bots(table_id)	Advance bots until it's the hero's turn or the hand ends.
advise(table_id, mc_trials)	Recommended action + equity + pot odds + EV rationale.
calc_equity(hole, board, num_opponents, mc_trials)	Monte Carlo equity estimate.
get_opponent_stats(player_id)	VPIP / PFR / AF for a player from stored hands.
import_hand_history(events)	Minimal stub to store externally-provided events.

Cards use standard two-character notation: rank (2-9, T, J, Q, K, A) + suit (c, d, h, s), e.g. As, Kh, Td.

Example flow

1. create_table(seats=6, hero_seat=0, bot_profile="mixed") → returns a table with an id.
2. get_pending_actions() → see which tables need you.
3. advise(table_id) → get a recommendation with equity and reasoning.
4. submit_action(table_id, "call") (or "raise" with amount) → bots play on; a new hand is dealt when one ends.

Project layout

poker-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── data/preflop_ranges/6max_rfi.json
├── src/poker_mcp/
│   ├── server.py            # FastMCP instance + tools
│   ├── config.py
│   ├── schemas.py           # pydantic IO models
│   ├── engine/              # table.py, manager.py, bots.py
│   ├── decision/            # equity.py, preflop.py, policy.py
│   └── modeling/            # store.py (sqlite), stats.py
└── tests/

The hand-history database defaults to poker_mcp.db in the working directory; override with the POKER_MCP_DB environment variable. Override the preflop chart directory with POKER_MCP_RANGES_DIR.

Development

uv sync --extra dev
uv run pytest -q

Roadmap (future phases, not in v1)

• GTO / solver integration (e.g. TexasSolver) for range-vs-range solving.
• Richer preflop/postflop range charts and 3-bet/4-bet logic.
• More sophisticated opponent models and exploitative adjustments.
• Opt-in live-play study aids. Any webcam/computer-vision "player read" feature is explicitly out of scope for v1 and would only ever be an opt-in study stub — never automation of a real-money client.

License

MIT © Vedant Mehta. See LICENSE.