SSB MCP ── Sharp Money Intelligence for AI Agents

SSB MCP ── Sharp Money Intelligence for AI Agents

SSB MCP is a Model Context Protocol server that lets AI agents see what the sharpest sportsbooks are doing. Its current registry covers 39 screen feeds across 12 league configs, detects coordinated sharp movement, surfaces steam moves and line lags, and explains the consensus — so you can decide what to bet, not be told.

Connect it to Claude Desktop, Cursor, Cline, Hermes, or any MCP client. Requires a PropProfessor account — the free tier is enough; no paid subscription needed.

Honest scope — no profitability claim: SSB MCP is a sharp-signal DISCOVERY and RATING tool. tier / kaiCall / edge / screenScore are signal-quality ratings, not win-probability predictions. Profitability is UNPROVEN — no settled-results backtest has been published yet. Use it to find candidate plays and validate them yourself; do not treat outputs as a guaranteed winning system. The ranking pipeline surfaces what sharp books are doing; the betting decision stays with you.

What this project demonstrates

• Agent integration — a 31-tool MCP surface with natural-language routing and structured responses
• Data pipelines — live odds extraction, line-history hydration, consensus scoring, and market-specific ranking
• Operational reliability — auth recovery, circuit breakers, caching, validation, and deterministic install checks
• Honest evaluation — synthetic validation is separated from real settled-results backtesting; unsupported win-rate claims are deliberately avoided

🚀 Overview

Your AI agent gets 31 tools that surface the same signal feed professional bettors use:

• Screen & rank — query the current 39-feed screen registry, ranked by consensus edge and movement
• Detect sharp coordination — Pinnacle, Circa, BookMaker, and BetOnline moving together? That's a signal
• Explain the "why" — every play comes with a human-readable rationale: what moved, on which books, over what timeframe
• Natural language routing — agents call ask("best plays on Fliff tonight") and get routed to the right tool automatically

The pipeline extracts odds, hydrates line history, ranks by movement quality + consensus strength, assigns a tier and risk score, and returns everything your agent needs to present an informed recommendation. The betting decision stays with the human.

⚡ Quickstart (30 seconds)

1. Clone and install: git clone https://github.com/jbdrak/ssb-for-agents.git && cd ssb-for-agents && npm ci && npm link

2. Wire your MCP client — pick your client below:

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "ssb": {
         "command": "pp",
         "args": ["--mcp"]
       }
     }
   }
   

   Cline (cline_mcp_settings.json):

   {
     "mcpServers": {
       "ssb": {
         "command": "pp",
         "args": ["--mcp"],
         "env": {}
       }
     }
   }
   

   Cursor — Settings → Features → MCP Servers → Add:

   Name: ssb
   Type: command
   Command: pp --mcp
   

   Continue.dev (~/.continue/config.json):

   {
     "experimental": {
       "mcpServers": {
         "ssb": {
           "command": "pp",
           "args": ["--mcp"]
         }
       }
     }
   }
   

   Hermes (~/.hermes/config.yaml):

   mcp_servers:
     ssb:
       command: pp
       args: [--mcp]
   

3. Auth (one-time): node scripts/pp-login.js — opens a browser for PropProfessor login and persists cookies for the server to use.

4. Ask your agent: "What are tonight's sharpest plays on Fliff?"

That's it — your agent now sees 31 tools.

Verify your install: npm run install:verify runs the credential-free install verification suite.

CLI — pp

SSB ships with a fast, standalone CLI that calls handlers directly — no MCP server needed.

git clone https://github.com/jbdrak/ssb-for-agents.git
cd ssb-for-agents
npm ci
npm link
pp scan mlb tennis -M supportive -n3

18 commands for scanning, validation, setup, and logging:

MCP mode: pp --mcp runs as an MCP stdio server. Connect it to Claude Desktop,Cursor, Cline, or any MCP client. Pass --mode full for the full 31-tool surface.

Quick start (from a clone): after npm link, run pp --mcp to start the MCP server. No global package download is required.Development/clone setup: use the full path — node /path/to/scripts/ssb-mcp-server.js — see MCP Client Setup below.

All commands support -j/--json for piping and --no-color for CI/Telegram output.

Example output (scan filtered by supportive movement):

MLB › Moneyline  (2)
  Houston Astros @ +127  |  TIER 1  ● BET
    1.9%  ·  clv +4¢  ·  mv supportive_bouncy  ·  5 books
    Chicago White Sox vs Houston Astros  Fri, Jul 24, 6:40 PM

Tennis › Total Games  (1)
  Under 21.5 @ -104  |  TIER 1  ● BET
    3.4%  ·  mv supportive_clean  ·  16 books
    Avanesyan vs Oliynykova  Fri, Jul 24, 7:00 AM

📊 Backtesting

SSB includes a backtest runner that prints settled-pick performance across any date range.

# Show last 30 days of settled picks
node scripts/backtest-runner.js --days 30

# Show a specific date range
node scripts/backtest-runner.js --from 2026-06-01 --to 2026-07-20

# Or use the installed binary
pp-backtest --days 30

The runner reads from ~/.ssb-for-agents/picks.json — the same file used by pp log and pp picks. It shows total picks, settled records, win rate, P&L, and breakdowns by tier and league. It never fabricates ROI. If no settled picks exist in the range, it says so honestly.

📒 Record Keeping — legacy tracker migration

The local record ledger (PP_RECORD_LEDGER, default ~/.ssb-for-agents/tracker/ledger.json) is the v2 source of truth for official bets. To import the old Python tracker's settled bets (~/.ssb-for-agents/tracker/bets.json) into the v2 ledger:

# Preview what would be imported (dry-run is the default — writes nothing)
node scripts/migrate-tracker.js

# Machine-readable preview
node scripts/migrate-tracker.js --json

# Actually migrate (backs up the destination ledger first)
node scripts/migrate-tracker.js --apply

Safety properties:

• Dry-run by default — --apply is required to write anything; --dry-run is explicit and conflicts with --apply.
• bets.json is never overwritten — it is read-only input, and the script refuses to run when the source and ledger paths resolve to the same file.
• Timestamped backup — before --apply writes, the existing destination ledger is copied to ledger.json.bak-<timestamp> (no backup is needed on first migration).
• Idempotent — legacy IDs are preserved, so re-running never double-counts.
• No guessed dates — legacy records carry no event date (only loggedAt/settledAt), so migrated bets get eventDate: "unknown" and can never appear in strict date-filtered reviews. The complete original record is preserved verbatim in each bet's legacy metadata, along with the legacy id, status, and P&L (plUnits).

Active workflow — record, review, settle

The day-to-day recordkeeping loop is manual and local-only; nothing polls SSB in the background:

# 1. Record the scan — snapshots the scan + normalized candidates into the ledger
pp scan --record-scan

# 2. Promote reviewed decision cards (BET → official bet; LEAN/PASS update the candidate only)
pp record-card card.json
pp record-card --json '<payload>'          # inline card JSON (single card or array)

# 3. Review the ledger (local, read-only)
pp record stats    --date 2026-08-04 --json
pp record review   --date 2026-08-04
pp record pending  --date 2026-08-04

# 4. Settle official bets against supplied authoritative results
node scripts/settle-record.js --results results.json --date 2026-08-04 --dry-run

Key properties:

• --record-scan is manual only — it records whenever you run pp scan --record-scan; there is no cron job or background poller hitting SSB on a schedule.
• Only BET promotes — pp record-card turns explicit BET cards into official bet records; LEAN/PASS update the candidate without creating a bet. Re-importing an already-recorded card is a no-op (idempotent).
• pp record is local and read-only — stats, review, and pending modes read the ledger with no network and no writes; --date filters by the America/Chicago calendar day of scheduled start, --json emits machine-readable output.
• Settlement never calls SSB — scripts/settle-record.js (and lib/record-settlement) contain no network code. You fetch results yourself (e.g. an ESPN scoreboard dump) and hand them over as a local JSON file; the script matches bets to final scores, computes P&L, and writes the ledger atomically. --dry-run reports without writing anything; --force re-settles bets that already have a settled status.
• Results file provenance is required — the results file must be an object with non-empty top-level provider and sourceUrl plus an events array; bare event arrays are no longer accepted. A same-ID event never settles on its ID alone: it must also match the bet's participants and fall inside the scheduled date window, and event-specific source URLs are kept only when the top-level provenance is valid. Missing provenance is a CLI usage error (the ledger is never touched), and library callers receive pending records with a precise reason instead of a settlement.
• PP_RECORD_LEDGER overrides the ledger path — every command above reads/writes $PP_RECORD_LEDGER when set, otherwise the default ~/.ssb-for-agents/tracker/ledger.json.

Offline record → settle → evaluate example

Run the complete lifecycle without credentials, network calls, or user-file writes:

node examples/record-settle-evaluate.js

The synthetic fixture records an immutable probability snapshot, promotes a reviewed card, settles it from supplied result data, and derives calibration from the v2 ledger. Its one-bet report is explicitly marked insufficient for accuracy or uplift claims. See Project status and evaluation roadmap for shipped capabilities and hard limits.

🏛 Architecture

SSB MCP follows a layered data pipeline:

API Layer

• SSB Backend — authenticated REST API for live odds, line history, and fantasy data
• ESPN Integration — live scores for tennis time correction and game verification
• X / Google News — player context (injury news, tweets) for bet validation

Ranking Pipeline (Node.js)

• Extract — parse raw odds payloads from the screen API, expand multi-book selections
• Hydrate — use SharpOdds as the primary movement-history source, with the authenticated PP history path as a fail-closed fallback; cache board/history reads within the bounded request
• Rank — score by consensus edge (% advantage over sharp consensus), CLV proxy (opening vs current line movement), and league-specific market priorities
• Tier — assign TIER 1–4 based on movement grade (green/yellow/red) × risk score (1–10) × sharp book confirmation, with hysteresis to prevent thrashing
• Format — output at three verbosity levels: minimal (plain English), standard (tier/edge/risk/rationale), full (raw movement data)

MCP Server (stdio)

• JSON-RPC over stdio — standard MCP transport with Content-Length framing (NDJSON optional)
• 31 tools — organized into situational, analytical, and research tiers
• Server-side validation — enforces input schemas at the server, not trusting the client
• Categorized errors — auth, backend, transport, validation, internal — each with structured recovery hints

Data Flow

flowchart LR
    subgraph BOOKS["39 Screen Feeds"]
        B1[Pinnacle]
        B2[Circa]
        B3[BookMaker]
        B4[BetOnline]
        B5[NoVigApp]
        B6[Fliff]
        BN[...33 more]
    end

    API[PropProfessor API]

    subgraph PIPE["Ranking Pipeline"]
        E[Extract odds]
        H[Hydrate with line history]
        R[Rank by movement + consensus]
        T[Tier + risk score]
    end

    subgraph OUTPUT["31 MCP Tools"];
        QS[quick_screen]
        T[today]
        SB[smart_bet]
        VP[validate_play]
        ASK[ask]
        OTH[...25 more]
    end

    CLIENT[Your AI Agent<br/>Claude / Cursor / Cline / Hermes]

    BOOKS --> API --> PIPE --> OUTPUT --> CLIENT
    CLIENT -. "you decide what to bet" .- BOOKS

🛠 Getting Started

Quick Start

git clone https://github.com/jbdrak/ssb-for-agents.git
cd ssb-for-agents
npm install
npm link
pp-query init          # auth + verification + config — all at once

pp-query init checks Node version, opens PropProfessor login if needed, runs doctor, and prints ready-to-paste MCP config for your client. Or do it step by step:

pp-query login         # browser login
pp-query doctor        # verify everything works

Requires a PropProfessor account — the free tier is sufficient. That's it — you're ready to connect your AI agent.

MCP Client Setup

Add to your client's MCP config:

{
  "mcpServers": {
    "ssb": {
      "command": "node",
      "args": ["/path/to/ssb-for-agents/scripts/ssb-mcp-server.js"],
      "env": {
        "SSB_MCP_NDJSON": "true",
        "AUTH_FILE": "/path/to/.ssb-for-agents/auth.json"
      }
    }
  }
}

Replace /path/to/ with your actual install path (e.g. /Users/you/projects/ssb-for-agents). Supports Claude Desktop, Cursor, Cline, Zed, Continue.dev, Windsurf, and any other stdio-based MCP client. See each client's docs for where MCP config lives.

For short-lived one-off sessions:

Clone the repository, install dependencies, and point your client at the server script:

{ "command": "node", "args": ["/path/to/ssb-for-agents/scripts/ssb-mcp-server.js"] }

Requires a local clone and a free PropProfessor account.

For headless/CI environments (no Chrome):

Set the SSB_COOKIES env var with your PropProfessor cookies exported as JSON. This bypasses the CDP/Chrome auth path entirely:

{
  "mcpServers": {
    "ssb": {
      "command": "node",
      "args": ["/path/to/ssb-for-agents/scripts/ssb-mcp-server.js"],
      "env": {
        "SSB_COOKIES": "[{\"name\":\"__Secure-next-auth.session-token\",\"value\":\"...\",\"domain\":\".propprofessor.com\"}]"
      }
    }
  }
}

Auth refresh fallbacks (optional). When the server-to-server token fetch is gated by Vercel (HTTP 429), the server self-heals via a logged-in browser. Fallback order is got-scraping → ego-browser → CDP: the ego-browser fallback (named task space pp-token-refresh, created on first use, unless SSB_EGO_TASK_SPACE is set to a positive integer task-space id) is tried first; the CDP fallback runs only if ego-browser fails. The CDP endpoint defaults to http://127.0.0.1:9222/json/version; set SSB_CDP_VERSION_URL (e.g. http://127.0.0.1:9333/json/version) to use a different Chrome-for-Testing listener. Both fallbacks are on-demand only — no polling.

Hermes Agent

If you use Hermes Agent:

make install          # register MCP server + install default config

Or manually: add ssb to your mcp_servers in config.yaml. The get_started tool provides on-demand workflow guidance.

Sharp-money alerts

SSB is manual-only. There is no supported cron, scheduled workflow,or background polling mode. Run quick_screen on demand when you want a freshresult.

🎯 The Natural Language Flow

ask is a query router — it parses natural language and returns a suggested tool + args, but it does NOT execute the tool. Your agent calls ask to figure out what to do, then makes the actual call:

You:  "Tell me the best plays on Fliff tonight"
Agent: ask({ query: "best plays on Fliff tonight" })
       → { parsed: { book: "Fliff" }, suggestedTool: "quick_screen", suggestedArgs: { books: ["Fliff"] } }
Agent: quick_screen({ books: ["Fliff"] })
       → [ranked plays with odds, edge, tier, risk, rationale — all on Fliff]

📊 Available Tools

Quick Situational Checks

get_market_registry returns main-line markets in the markets field and exact player/pitcher prop names in the propMarkets field. scan and quick_screen accept includeProps:true to merge those prop markets into a scan. Prop scans are manual-only because they increase backend fan-out and rate-limit risk.

Deeper Signal Analysis

Research & Bet Management

Output Tuning

Every tool accepts:

quick_screen additionally accepts:

Player research is ON by default in quick_screen (pass includeResearch: false to disable). It's scoped to the final returned plays and de-duplicated per game, so research always maps 1:1 to what you got back. On a huge unfiltered scan, lower researchLimit or use lite if the response nears the transport cap.

cardWindow honesty: when today is alive and next-day rows are merged, the response reports cardWindow: "today" (not tomorrow's date) plus nextDayMerged: true and nextDayDate. Earlier builds mislabeled this as tomorrow — that bug is fixed.

Tier consistency: as of 2.8.x, tierCache is cleared at the start of every MCP screen call (quick_screen, screen_ranked, validate_play). A given play's tier is therefore stable within a call and recomputed fresh per call — no cross-call drift from stale hysteresis state.

verbosity: minimal returns a plain-English summary string WITH a structured plays array — agents get both human-readable text and machine-parseable data in one call. Each play in the array includes league, market, game, selection, odds, confidenceTier, edge, startCST, movementDisposition, and screenScore.

Tool Surface Modes

Set SSB_MCP_MODE at server boot to control how many tools the agent sees on tools/list:

Lite mode exposes: ask, smart_bet, quick_screen, today, find_best_price, validate_play, get_play_details, player_context, log_pick, get_pick_history, resolve_pick, get_market_registry, place_bet, sharp_alerts, health_status.

The tools/list response always includes a _meta block so agents can tell which mode is active:

{
  "tools": [...],
  "_meta": { "mode": "full", "toolCount": 31, "liteToolCount": 15, "fullToolCount": 31 }
}

Tool Categories

Every tool carries a category field that groups it by purpose — agents can use this to mentally cluster the surface rather than reading 29 individual descriptions:

Canonical vs Deprecated Param Names

A handful of params accept both a clean canonical name and a legacy alias — every existing call site keeps working, and new code can use the cleaner names:

Deprecated aliases are documented in each schema's description field and are normalized to the canonical key at dispatch time. No code change required for existing callers.

🧪 How the Ranking Works

The pipeline grades every play in 5 steps:

1. Movement grade — green (all sharp books aligned), yellow (some signals, some not), red (adverse)
2. Risk score (1–10) — weighted from movement quality, consensus count, CLV strength, execution quality, and freshness
3. Tier assignment — lookup table: green + low risk → TIER 1, green-yellow + moderate → TIER 2, yellow → TIER 3, red → TIER 4
4. Hysteresis — a play doesn't thrash between TIER 1 and TIER 3 on small odds changes; tier trajectory is smoothed
5. Sharp cross-reference — verifies target-book moves independently against non-target sharp books

Tier system:

Full methodology, weight tables, and the tier assignment lookup in docs/METHODOLOGY.md. Backtesting results in docs/BACKTESTING.md.

🔌 Integrations

See Quick Start for Hermes Agent setup. The MCP is self-documenting — agents call get_started to discover the right workflow.

Discord / Telegram Alerts

The Positive EV Command Center is a companion project that monitors SSB for high-EV slips and plays, then pushes them to Discord and Telegram in real-time. It uses the same auth session and API client.

pp-query CLI

pp-query is a standalone CLI for one-off queries without an MCP client. Soccer is queried from the generic Soccer backend feed; named competitions are filtered by their leagueName (the same model used by the frontend):

pp-query screen --league NBA --market Moneyline
pp-query screen --league EPL --market "Total Goals"
pp-query screen --league Soccer --league-name EPL --market "Total Goals"
pp-query recommended --leagues NBA,MLB
pp-query login
pp-query doctor

📈 Validation methodology

TL;DR: The infrastructure is in place. Real outcome data hasn't accumulated yet.

Two paths to validate the signal:

1. Synthetic engine validation — runs generated scenarios (sharp_move,stable_no_edge, adverse) through the full pipeline to confirm the tier systemactually differentiates quality:

node scripts/backtest-synthetic.js

2. Real outcome backtest — snapshot-based, since the PropProfessor API doesnot serve historical settled results. Take a pre-game odds snapshot daily, thenresolve outcomes as games settle:

# capture today's recommended plays
node scripts/daily-snapshot.js
# after games settle, apply win/loss/push via CSV
node scripts/resolve-outcomes.js --csv results.csv
# compute P&L, ROI, Sharpe, max drawdown from resolved data
node scripts/backtest.js --metrics data/snapshots.jsonl

The pipeline (daily-snapshot.js → settle games → resolve-outcomes.js →backtest.js --metrics) is built and tested (full deterministic pipeline suitepasses). What's missing: real settled-results data. The synthetictier-validation run shows a TIER 1 hit rate of 51.4% over N=296 simulatedsamples — these validate the ranking engine, they do NOT prove profitability.

Honesty: tier/kaiCall/edge/screenScore are signal-quality ratings, notwin-probability predictions. Profitability is UNPROVEN — no settled-resultsbacktest has been published yet. The system surfaces what sharp books aredoing; it doesn't come with a bundled historical results feed. Don't trust awin rate you can't trace to settled bets. See docs/BACKTESTING.md.

🔧 Troubleshooting

Still stuck? Run pp-query doctor and open an issue with the output.

❓ FAQ

Does this tell me what to bet? No. It surfaces what sharp books are doing. The betting decision is yours.

Do I need a PropProfessor account? Yes, and the free account is enough. Live data works on the free tier at propprofessor.com — no paid subscription required.

What books does it cover? The code currently registers 39 screen feeds across 12 league configs. Some entries are alternate or specialized feeds rather than distinct sportsbooks. Sharp cross-reference: Pinnacle, Circa, BookMaker, BetOnline.

Is it free? Code is MIT-licensed, and a free PropProfessor account covers the data. There is no paid tier of the MCP itself.

Can I run it without an MCP client? Yes — pp doctor is a standalone CLI.

What if I find a bug? Run pp doctor first, then open an issue.

⭐ Support

This is free, MIT-licensed software. If it saves you time or makes you money:

• ⭐ Star the repo — helps others find it
• 🐛 Open an issue when you find a bug
• 💸 Sponsor on GitHub — funds ongoing development

No paid tier. No upsell. The whole codebase is open and the priority is making it better for the people who use it.

🔧 For Maintainers

npm test              # full deterministic suite passes (no exact count — see check:claims)
npm run test:coverage # ~82% statements
npm run lint          # clean
npm run format:check  # clean (npm run format to fix)
npm run check:version # verifies package.json ↔ CHANGELOG

Release: push a v* tag → CI runs lint + tests on Node 20 + 22 → publishes to npm → creates the GitHub release.

📚 Docs Index

📝 License

MIT. PropProfessor offers a free tier; this MCP is an unofficial client built by James Drake, not affiliated with PropProfessor.