Scottfree Sports CLI & MCP Server

Command-line tool and MCP server for the Scottfree Analytics sports predictions API. Every Scottfree Sports AI subscriber can use it to gather model picks, line movement, odds, model history, public consensus, weather, live scores, injuries, rosters, and prediction-market context from the terminal or an AI assistant.

Installation

Version 0.3.0 adds full historical results access and recorded-price strategy accounting. Deploy the compatible API before upgrading clients. Restart your MCP host after upgrading; an API deployment alone cannot update installed tools.

sfs results seasons nhl spread
sfs results get nhl spread --season 2023-24 --all --json

get_result_seasons discovers labels. MCP get_results accepts season, limit, offset, and snapshot; continue using the returned next_offset and original snapshot until next_offset is null. Changed artifacts require restarting. Results contain available model-bearing history, not every historical game.

Strategy commands request recorded_v2 and reject older assumed-price responses. Prices are selected-side recorded odds, pushes return the stake, and unpriceable or unverified-final games are excluded and counted. Missing odds never become -110.

# From PyPI (recommended)
pip install scottfree-sports-cli

# Or with uv
uv tool install scottfree-sports-cli

# From repo (development)
cd sflow-cli && uv sync --dev

Quick Start

# Configure your API key
sfs config set --api-key sk_alphapysports_... --env default

# For local development
sfs config set --api-key dev_local_alphapy_key --api-url http://localhost:8009 --env local

# Get today's predictions
sfs predictions get nba spread
sfs predictions get mlb over_under

# List available sports and models
sfs predictions list-sports

Commands

sfs
  brief         Daily model research briefing
  config        Manage API configuration and profiles
  predictions   Get game predictions
  results       Get historical prediction results
  summary       Get model performance summaries
  odds          Get current betting odds
  markets       Prediction market odds
  consensus     Public betting consensus
  weather       Game-day weather for outdoor venues
  scores        Live scores and injury reports
  account       Manage your account
  admin         Admin operations (Scottfree admin only)

Brief — the model research command

Combines model predictions with market lines for every game on the slate. The brief shows ML model picks, model probability, market-implied probability, signed Delta(Model-Implied), and model-position counts. It does not claim a guaranteed edge, Kelly sizing, or EV.

sfs brief get mlb                # Today's MLB games
sfs brief get nhl                # NHL playoff games
sfs brief get mlb -o json        # Structured JSON

Predictions

sfs predictions get nba spread          # Table output (default)
sfs predictions get nba spread -o json  # JSON output (pipeable)
sfs predictions get nfl ml -o csv       # CSV output
sfs predictions list-sports             # Available sports & models

Results & Summary

sfs results get nba spread --limit 20
sfs summary get nhl over_under

Line Movement

The CLI exposes the same opener/current fields used by the app's Predictions and Summary pages:

sfs predictions get mlb over_under -o json
sfs predictions get mlb spread -o json
sfs predictions get mlb ml -o json

Relevant fields include open_over_under, over_under, open_home_point_spread, home_point_spread, open_home_money_line, home_money_line, open_away_money_line, and away_money_line.

Odds

sfs odds get nba

sfs odds get renders a terminal table today. Use the REST API directly for full JSON:

curl -H "X-API-Key: $SFS_API_KEY" \
  https://sports-api.scottfreellc.com/api/v1/odds/mlb

Public Consensus, Weather, Scores, Injuries, and Markets

sfs consensus get mlb
sfs weather get mlb
sfs scores scores mlb
sfs scores injuries nba
sfs scores players nba --search "James"
sfs markets kalshi nfl
sfs markets polymarket nba
sfs markets compare mlb

AI Analysis

Scottfree Sports does not generate AI narratives. Connect the MCP server to Claude Desktop, Claude Code, Cursor, or another compatible MCP host and ask anything in natural language — your LLM synthesizes answers using the data tools above with your own API key. ChatGPT support depends on your ChatGPT plan/workspace supporting custom remote MCP apps/connectors.

Account Management

sfs account info                          # Account details
sfs account usage                         # API usage stats
sfs account keys                          # List API keys
sfs account create-key --name "CLI Key"   # Create new key
sfs account rename-key sk_... --name "X"  # Rename key
sfs account revoke-key sk_...             # Revoke key

Output Formats

Flag	Format	Use Case
-o table	Rich table (default)	Terminal viewing
-o json	Raw JSON	Piping to jq, scripts
-o csv	CSV	Spreadsheets, data analysis

Configuration

Config is stored in ~/.sfs/config.toml:

[default]
api_key = "sk_alphapysports_..."
api_url = "https://sports-api.scottfreellc.com"

[local]
api_key = "dev_local_alphapy_key"
api_url = "http://localhost:8009"

Resolution Order

1. SFS_API_KEY / SFS_API_URL environment variables (highest)
2. --env flag selects a profile
3. [default] profile (lowest)

Model Type Shorthands

Shorthand	Full Value
spread	won_on_spread
moneyline, ml	won_on_points
over_under, ou	over_under

MCP Server

The sfs-mcp command exposes predictions as tools for AI assistants (Claude Code, Claude Desktop).

Claude Code Setup

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "scottfree-sports": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/sflow-cli", "sfs-mcp"],
      "env": {
        "SFS_API_KEY": "sk_alphapysports_...",
        "SFS_API_URL": "https://sports-api.scottfreellc.com"
      }
    }
  }
}

Available MCP Tools

Tool	Description
get_daily_brief	Daily model research brief with ML model picks
get_predictions	ML predictions for today's games
get_results	Historical prediction results
get_result_seasons	Discover all available historical model-result seasons
get_summary	Model performance metrics
get_odds	Current betting odds
get_sports	List sports and model types
get_account_info	Account details
get_usage	API usage statistics
get_kalshi_markets	Kalshi prediction market prices
get_polymarket_odds	Polymarket prediction market odds
compare_market_odds	Cross-reference markets vs ML model
get_betting_consensus	Public betting percentages
get_game_weather	Game-day weather for outdoor venues
get_live_scores	Live game scores
get_injuries	Current injury reports
get_players	Player rosters
clear_cache	Clear cache (admin)
invalidate_cache	Invalidate specific cache entries (admin)

Supported Sports

MLB, NBA, NCAAB, NCAAF, NFL, NHL

Complete Documentation

• API reference: https://scottfreellc.github.io/alphapy-sports/api/endpoints
• CLI reference: https://scottfreellc.github.io/alphapy-sports/cli/
• MCP setup and tool reference: https://scottfreellc.github.io/alphapy-sports/mcp/

Development

cd sflow-cli
uv sync --dev
uv run pytest tests/ -v        # Run tests
uv run ruff check src/ tests/  # Lint