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.4.0 shows how results and model tracking are graded: result rows carry a push marker, sfs models tracking prints the season's game range, source, ungraded pushes and grading notes, and sfs summary get shows wins, losses and graded games. Pushes (a final exactly on the line) are never counted as wins or losses. Older API responses without these fields still display. Restart your MCP host after upgrading; an API deployment alone cannot update installed tools.

Version 0.3.0 added full historical results access and recorded-price strategy accounting.

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
sfs models tracking nhl over_under --season 2023-24

How grading works, on every surface (API, CLI, MCP):

• A push (a total or spread on the number, a tied moneyline game) has no outcome. Result rows carry push: true; the stored outcome columns stay binary, so leave pushes out when counting hits. Model tracking reports ungraded_pushes.
• A tracking season grades exactly the games in its results archive, with the archive's scores and prices; preseason and other seasons' games are excluded.
• Consensus counts only games where all six models vote and none sits at 50%.
• The 1-week and 4-week windows sit inside the season: overlapping views of the same games, not independent samples.

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

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

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

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