PropProfessor MCP ── Sharp Money Intelligence for AI Agents

PropProfessor MCP is a Model Context Protocol server that lets AI agents see what the sharpest sportsbooks are doing. It screens 36 books across 10 leagues, 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.

Honest scope: This is a sharp-money signal feed, not a betting oracle. The ranking pipeline detects what sharp books are doing — it does not predict outcomes. TIER 1 hit rate sits around chance (~50%). Use it to inform your own handicapping, not to outsource decisions.

🚀 Overview

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

• Screen & rank — query live odds across 36 sportsbooks, 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.

Related MCP server: RDF Explorer

🏛 Architecture

PropProfessor MCP follows a layered data pipeline:

API Layer

• PropProfessor 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 — enrich each row with 12-hour odds history via the backend API (cached cross-call with 5-min TTL)

• 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)

• 30 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["36 Sportsbooks"]
        B1[Pinnacle]
        B2[Circa]
        B3[BookMaker]
        B4[BetOnline]
        B5[NoVigApp]
        B6[Fliff]
        BN[...30 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["29 MCP Tools"];
        RB[recommended_bets]
        SP[sharp_plays]
        SC[sharp_consensus]
        SR[screen_ranked]
        QS[quick_screen]
        SB[smart_bet]
        ASK[ask]
        OTH[...23 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/j17drake/propprofessor-mcp.git
cd propprofessor-mcp
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 paid PropProfessor account. That's it — you're ready to connect your AI agent.

MCP Client Setup

Add to your client's MCP config:

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

Replace /path/to/ with your actual install path (e.g. /Users/you/projects/propprofessor-mcp). 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:

{ "command": "npx", "args": ["-y", "propprofessor-mcp"] }

Works out of the box — no git clone needed. Requires a PropProfessor account.

For headless/CI environments (no Chrome):

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

{
  "mcpServers": {
    "propprofessor": {
      "command": "npx",
      "args": ["-y", "propprofessor-mcp"],
      "env": {
        "PROPPROFESSOR_COOKIES": "[{\"name\":\"__Secure-next-auth.session-token\",\"value\":\"...\",\"domain\":\".propprofessor.com\"}]"
      }
    }
  }
}

CLI Commands

Hermes Agent

If you use Hermes Agent:

make install          # register MCP server + install default config

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

Optional: Sharp-money alert cron

make install-cron

Runs hourly, delivers TIER 1 plays to your home Telegram channel.

CLI commands

🎯 The Natural Language Flow

Agents don't need to memorize tool names. Call ask to parse a user's query, then call the suggested tool:

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

Deeper Signal Analysis

Research & Bet Management

Output Tuning

Every tool accepts:

quick_screen and recommended_bets additionally accept:

Player research is ON by default in quick_screen and recommended_bets (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, recommended_bets, 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, not structured JSON — agents that need to parse the response must use standard/full, OR pass parseable: true on minimal to get a structured plays array next to the summary.

Tool Surface Modes

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

Lite mode exposes: ask, smart_bet, tonight_bets, recommended_bets, quick_screen, find_best_price, validate_play, get_play_details, player_context, log_pick, get_pick_history, resolve_pick, get_market_registry.

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

{
  "tools": [...],
  "_meta": { "mode": "full", "toolCount": 29, "liteToolCount": 13, "fullToolCount": 29 }
}

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 PropProfessor 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.

CLI

pp-query is a standalone CLI for one-off queries without an MCP client:

pp-query screen --league NBA --market Moneyline
pp-query recommended --leagues NBA,MLB
pp-query login
pp-query doctor

📈 Backtesting

Validated via synthetic scenarios (sharp_move, stable_no_edge, adverse) and daily snapshots of pre-game odds:

node scripts/backtest-synthetic.js

TIER 1 hit rate sits around chance (~50%) — expected, because the system measures signal quality, not predictive power. See docs/BACKTESTING.md.

❓ 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. Live data requires a paid subscription at propprofessor.com.

What books does it cover? 36 sportsbooks across 10 leagues. Sharp cross-reference: Pinnacle, Circa, BookMaker, BetOnline.

Is it free? Code is MIT-licensed. Data requires a paid PropProfessor subscription. No paid tier of the MCP itself.

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

What if I find a bug? Run pp-query 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              # 1396 tests, 0 failures
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
npm run smoke:live    # end-to-end live smoke (requires auth.json)

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

Docs index

• Quick Start — install, auth, MCP client configs, troubleshooting

• Auth & Session Management — auth flow, session management

• CONFIG.md — env vars, book config

• CONTRIBUTING.md — how to add a tool

• SECURITY.md — auth handling, threat model

• MAINTAINERS.md — release process

• docs/METHODOLOGY.md — full ranking methodology

• docs/BACKTESTING.md — tier validation

• docs/MARKET-BOOK-AVAILABILITY.md — book/market matrix

• docs/AGENT_PROMPT.md — system prompt for agents

• docs/RELEASES.md — full release history

📝 License

MIT. PropProfessor is a paid service; this MCP is an unofficial client built by j17drake, not affiliated with PropProfessor.