Skip to main content
Glama
poker-mcp

poker-mcp

by vedsmehta

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.

Related MCP server: MCP Poker

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.

Available Tools

11 tools
adviseA

Recommend a hero action combining equity, pot odds, and preflop charts.

Args: table_id: Target table id (must be the hero's turn). mc_trials: Monte Carlo rollouts used for the equity estimate.

Inputs: table_id (required), mc_trials. Returns: equity, sizing, street, position, +8 more

autoplay_botsA

Advance non-hero bots until it is the hero's turn or the hand ends.

Inputs: table_id (required). Returns: pot, board, seats, street, +12 more

calc_equityA

Estimate hero equity via Monte Carlo against random opponents.

Args: hole: Hero's two hole cards, e.g. ["As", "Ah"]. board: Known community cards (0, 3, 4, or 5), e.g. ["Kd", "7c", "2h"]. num_opponents: Number of random opponents to simulate against. mc_trials: Number of random rollouts to run.

Inputs: hole (required), board, mc_trials, num_opponents. Returns: tie, win, loss, equity, +2 more

close_tableB

Close and remove a table by id. Returns whether it existed.

Inputs: table_id (required). Returns: object

create_tableA

Create a new simulated no-limit hold'em table and deal the first hand.

Args: seats: Number of seats (players) at the table (2-9). small_blind: Small blind size in chips. big_blind: Big blind size in chips (> small_blind). starting_stack: Starting stack for each seat. hero_seat: Seat index controlled by you (the hero). bot_profile: Opponent style: 'mixed', 'random', 'tight', or 'station'.

Returns a snapshot of the table; bots are auto-advanced until it is the hero's turn or the hand ends.

Inputs: seats, big_blind, hero_seat, bot_profile, +2 more. Returns: pot, board, seats, street, +12 more

get_opponent_statsA

Return aggregate stats (VPIP/PFR/AF) for a player from stored hands.

Inputs: player_id (required). Returns: af, pfr, bets, vpip, +4 more

get_pending_actionsA

Return every table currently waiting on the hero to act.

This is the multi-table driver: poll it to find which tables need a decision, act on one via submit_action, then poll again.

Inputs: no named parameters. Returns: result

get_table_stateC

Return the full current state summary for a table.

Inputs: table_id (required). Returns: pot, board, seats, street, +12 more

import_hand_historyB

Import raw hand-history events into the store (minimal stub).

Each event is {hand_id, player_id, street, action, amount, voluntary, table_id}. This lets you seed opponent stats from external data.

Inputs: events (required). Returns: players, imported

list_tablesA

List all open tables with their current state summaries.

Inputs: no named parameters. Returns: result

submit_actionA

Submit the hero's action, then auto-advance bots to the next decision.

Args: table_id: Target table id. action: One of 'fold', 'check', 'call', 'bet', 'raise'. amount: Total chips to bet/raise to (required for bet/raise).

After applying the action, bots play out until it is the hero's turn again or the current hand ends (a fresh hand is then dealt).

Inputs: action (required), table_id (required), amount. Returns: pot, board, seats, street, +12 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: table lifecycle (create/get/list/close), acting (submit/autoplay/pending), and analysis (advise/equity/stats). The only near-overlap, list_tables versus get_pending_actions, is clearly separated by 'all tables' versus 'tables waiting on hero.'

    Naming Consistency4/5

    Most tools follow a clean verb_noun snake_case pattern such as create_table, close_table, get_table_state, and submit_action. Minor deviations like 'advise' (verb only) and 'calc_equity' (abbreviated verb) do not undermine the overall consistency.

    Tool Count5/5

    11 tools is well-scoped for a poker simulation server covering table lifecycle, decision-making, and analysis. Every tool maps to a meaningful workflow step with no obvious redundancy or bloat.

    Completeness4/5

    Core table workflows are complete: create, list, get state, submit actions, advance bots, and poll pending decisions. The analysis side is solid, but import_hand_history is explicitly a stub and there is no direct hand-history query, leaving a minor gap for deeper opponent data exploration.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with the TexasSolver poker solver to run game theory optimal (GTO) poker calculations, load preflop ranges, and build game trees with structured parameters for analyzing poker hands and strategies.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides poker play recommendations by combining real-time Monte Carlo equity calculations with historical player tracking and exploit-based advice. It enables users to import PokerNow hand histories to analyze player tendencies and receive data-driven coaching for various game situations.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to play virtual-chip poker games like Texas Hold'em and Zha Jin Hua against bot opponents within Codex, with interactive UI or text commands.
      MIT