# 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
```bash
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:
```json
{
"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.
