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: Race MCP Server

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

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.