# poker-mcp

A **poker study / decision-support** [MCP](https://modelcontextprotocol.io) 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`](https://pypi.org/project/mcp/) — the official Python MCP SDK (`FastMCP`, stdio transport).
- [`pokerkit`](https://pypi.org/project/pokerkit/) — poker game engine and hand evaluation (`NoLimitTexasHoldem`, `StandardHighHand`).
- [`pydantic`](https://pypi.org/project/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`](https://docs.astral.sh/uv/).

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

## Run

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

```json
{
  "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

```bash
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](LICENSE).