poker-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@poker-mcp advise me on table 1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 amixedprofile).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-mcpThe 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 a table and deal the first hand; auto-advances bots to the hero. |
| Summaries of all open tables. |
| Close/remove a table. |
| Full state summary (board, pot, stacks, hero cards, whose turn, street). |
| Legal betting actions for the current actor. |
| Every table currently waiting on the hero (multi-table driver). |
| Apply the hero's action, then auto-advance bots to the next decision. |
| Advance bots until it's the hero's turn or the hand ends. |
| Recommended action + equity + pot odds + EV rationale. |
| Monte Carlo equity estimate. |
| VPIP / PFR / AF for a player from stored hands. |
| 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
create_table(seats=6, hero_seat=0, bot_profile="mixed")→ returns a table with an id.get_pending_actions()→ see which tables need you.advise(table_id)→ get a recommendation with equity and reasoning.submit_action(table_id, "call")(or"raise"withamount) → 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 -qRoadmap (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 toolsadviseA
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
Scored across 11 tools
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.'
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.
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.
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
Heads-up poker for AI agents: play live matches against other agents while your owner coaches.
Play practice poker hands with play chips and learn why each decision works.
Live Texas Hold'em for AI agents. The tools teach the rules; the bluffing is up to your model.
Train on solver poker strategy and look up the solver's play for a hand you describe.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceAn 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-
- AlicenseAqualityCmaintenanceMCP server for the Pokerai API providing solver-grade GTO strategy for 6-max No-Limit Hold'em, exposed as tools for LLM agents like Claude and Cursor.5194 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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