MCP Poker

An MCP server for poker play recommendations — real equity calculations, player tracking, and exploit-based recommendations.

How It Works

• Equity engine: Monte Carlo simulation using phevaluator (a fast C-based poker hand evaluator). Suits, flushes, and all hand types are fully accounted for. No hardcoded hand rankings — everything is computed.
• Player tracking: Imports PokerNow hand histories, stores all hands/actions in SQLite, and computes detailed player statistics (VPIP, PFR, 3-bet, c-bet, aggression, WTSD, etc.)
• Exploit engine: Detects player leaks from historical data and adjusts GTO recommendations to exploit specific tendencies.
• Multi-way aware: Advice adjusts based on number of players in the hand — bluffing less in multi-way, tightening value ranges, accounting for equity dilution.

Architecture

src/                          # TypeScript source (MCP server)
├── index.ts                  # Entry point — wires tools to MCP server
├── tools/
│   ├── import.ts             # import_pokernow_log, set_hero, set_player_alias, add_player_note
│   ├── player.ts             # get_player_stats, get_player_tendencies, get_player_profile, list_players
│   ├── recommend.ts          # recommend_action (main coaching tool)
│   ├── history.ts            # search_hands, analyze_hand, get_session_summary, list_sessions
│   └── guide.ts              # get_tool_guide (LLM documentation)
├── gto/
│   ├── preflop-ranges.ts     # Equity-driven preflop advice (no hardcoded ranges)
│   ├── postflop.ts           # MC equity calculator bridge + postflop advice engine
│   └── exploit.ts            # Player leak detection + exploit adjustments
├── db/
│   ├── schema.ts             # SQLite schema + auto-migration
│   └── queries.ts            # All DB queries + stat calculations + player profiles
└── types.ts                  # Shared TypeScript types

python/                       # Python (equity calculations, CSV parsing)
├── equity_calculator.py      # Monte Carlo equity calculator using phevaluator
├── parse_pokernow.py         # PokerNow CSV log parser
└── requirements.txt

data/                         # SQLite database (created at runtime, gitignored)

• src/ = TypeScript source code
• dist/ = Compiled JavaScript output (gitignored, built by npm run build)
• python/ = Python scripts called by the TS server
• .venv/ = Python virtual environment with phevaluator

Setup

Prerequisites

• Node.js >= 18
• Python 3.8+

Install

npm install
npm run build
python3 -m venv .venv
.venv/bin/pip install phevaluator

Add to Cursor

The .cursor/mcp.json is already configured. After opening this project in Cursor, the server should be available. If not, add to your MCP config:

{
  "mcpServers": {
    "poker": {
      "command": "node",
      "args": ["/path/to/mcp-poker/dist/index.js"]
    }
  }
}

Tools (14 total)

Tool	Description
import_pokernow_log	Import a PokerNow CSV hand history file
set_hero	Set which player is you
set_player_alias	Link two PokerNow IDs as the same person
add_player_note	Save a note about a player
get_player_stats	Full stat sheet (VPIP, PFR, 3-bet, c-bet, AF, WTSD, etc.)
get_player_tendencies	Natural language leak analysis + exploit recommendations
get_player_profile	Comprehensive behavioral dossier (positional, multi-way, trends, showdowns)
list_players	List all tracked players
recommend_action	Real-time coaching with Monte Carlo equity + exploit adjustments
search_hands	Query hand history with filters
analyze_hand	Deep replay of a specific hand
get_session_summary	Session results + biggest pots
list_sessions	List all imported sessions
get_tool_guide	Returns full documentation on all tools for the LLM

For detailed input/output specs for every tool, call get_tool_guide from the LLM or see src/tools/guide.ts.

Data Storage

All data is stored locally in data/poker.db (SQLite). Nothing leaves your machine.