Poker Coach Engine

A small MCP math engine for a No-Limit Texas Hold'em Poker Coach Agent.

What it does

The MCP server exposes one tool: poker_analyze.

It can return:

• current hand class
• Hero equity versus a supplied Villain range
• fallback equity versus random opponent cards
• required equity / pot odds for a call
• call EV relative to folding
• SPR
• next-card hand-improvement outs
• board classification
• basic legal-action validation

It intentionally does not invent GTO frequencies or final strategy. Your Agent should combine this tool with its poker strategy / GTO knowledge base and opponent model.

Supported range notation (v0.1)

Examples:

AA
77,22,A7s,A2s,AQs,AJs
99+
AJs+
A5s-A2s
76s-54s
AKs
AKo
AK
AhKh
A5s:0.5

A5s:0.5 means the combo class is weighted at 50% when sampled.

Important input definition

pot_before_call means the pot already in the middle after Villain's current bet/raise has gone in, but before Hero calls.

Example:

• 38 BB is currently in the pot
• Hero needs 11 BB more to call

Use:

pot_before_call = 38
call_amount = 11

The required equity is 11 / (38 + 11) = 22.45%.

Local install

Requires Python 3.10+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .

Run the MCP server over stdio:

poker-coach-engine

Test the math modules

PYTHONPATH=src python -m unittest discover -s tests -v

On Windows PowerShell:

$env:PYTHONPATH="src"
python -m unittest discover -s tests -v

Build for PyPI

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Upload to TestPyPI first if desired, then publish to PyPI.

After it is public on PyPI, Alibaba Cloud Model Studio can launch a Python MCP package through uvx <package-name>.

Bailian MCP config

After publishing the package, use:

{
  "mcpServers": {
    "poker-engine": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "poker-coach-engine"
      ]
    }
  }
}

If PyPI says the package name is already taken, rename [project].name in pyproject.toml, publish using that new name, and put the same new name in the args array.

Safety / scope

This package performs poker math and simulation. It does not interact with poker clients, automate gameplay, obtain hidden cards, or bypass platform rules.