scottfree-sports-cli 0.2.0

CLI and MCP server for Scottfree Analytics sports predictions API

Scottfree Sports CLI & MCP Server

Command-line tool and MCP server for the Scottfree Analytics sports predictions API.

Installation

# 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
  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
  analysis      Get AI-powered game analysis (premium)
  account       Manage your account
  admin         Admin operations (Scottfree admin only)

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

Odds

sfs odds get nba
sfs odds get mlb -o json | jq '.odds[:3]'

AI Analysis (Premium)

sfs analysis get nba spread

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://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://api.scottfreellc.com"
      }
    }
  }
}

Available MCP Tools

Tool	Description
get_predictions	ML predictions for today's games
get_results	Historical prediction results
get_summary	Model performance metrics
get_odds	Current betting odds
get_ai_analysis	AI-powered analysis (premium)
get_sports	List sports and model types
get_account_info	Account details
get_usage	API usage statistics
clear_cache	Clear cache (admin)
invalidate_cache	Invalidate specific cache entries (admin)

Supported Sports

MLB, NBA, NCAAB, NCAAF, NFL, NHL

Development

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