Skip to main content
Glama
kenpom

kenpom

by omalleyandy

KenPom Client

A Python API client and MCP server for KenPom basketball analytics. Get direct access to efficiency ratings, game predictions, and advanced stats through Claude or the command line.

Features

  • MCP Server: 11 tools for interactive analysis with Claude

  • Full API Coverage: All 9 KenPom API endpoints

  • Smart Analytics: Matchup comparisons, top team rankings

  • Resilience: Rate limiting, retries, and caching built-in

  • Multi-Format Export: CSV, JSON, and Parquet

Related MCP server: College Basketball Stats MCP Server

Quick Start

cd kenpom-client
uv venv && uv sync
cp .env.example .env  # Add your KENPOM_API_KEY

MCP Server Setup (Claude Code)

The MCP server lets Claude directly query KenPom data during conversations.

Step 1: Project Configuration

The .mcp.json file is already included in this project:

{
  "mcpServers": {
    "kenpom": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/omall/Documents/python_projects/kenpom-client",
        "run",
        "kenpom-mcp"
      ]
    }
  }
}

Step 2: Enable Project MCP Servers

Add this to your Claude Code settings (~/.claude/settings.json):

{
  "enableAllProjectMcpServers": true
}

Or manually approve the server when prompted by Claude Code.

Step 3: Restart Claude Code

Start a new session in the kenpom-client directory. The MCP server will load automatically.

Available MCP Tools

Tool

Description

kenpom_ratings

Current efficiency ratings (AdjOE, AdjDE, AdjEM)

kenpom_predictions

Game predictions with spreads and win probability

kenpom_matchup

Head-to-head comparison of two teams

kenpom_top_teams

Top N teams by any metric

kenpom_fourfactors

Four Factors analytics (eFG%, TO%, OR%, FT Rate)

kenpom_pointdist

Point distribution (% from FT, 2P, 3P)

kenpom_height

Height, experience, and continuity

kenpom_miscstats

Shooting %, blocks, steals, assists

kenpom_teams

Team rosters with coach and arena

kenpom_conferences

Conference list

kenpom_archive

Historical ratings from past dates

Example Queries

Once configured, ask Claude naturally:

  • "What are Duke's efficiency ratings?"

  • "Compare Auburn and Alabama head-to-head"

  • "Show me the top 10 teams by AdjEM"

  • "What games are predicted for today?"

  • "Which teams have the best four factors on offense?"

CLI Commands

For batch data collection and ML pipelines:

# Core data
uv run kenpom teams --y 2025
uv run kenpom conferences --y 2025
uv run kenpom ratings --y 2025 --date 2024-12-21

# Game predictions
uv run kenpom fanmatch --date 2024-12-21

# Advanced analytics
uv run kenpom fourfactors --y 2025
uv run kenpom pointdist --y 2025
uv run kenpom height --y 2025
uv run kenpom miscstats --y 2025

# Historical data
uv run kenpom archive --date 2024-12-21

# Real market odds (overtime.ag)
uv run fetch-odds

Output File Naming

All files follow: kenpom_{data_type}_{identifiers}.{ext}

Command

Example Output

teams

kenpom_teams_2025.csv

conferences

kenpom_conferences_2025.csv

ratings

kenpom_ratings_2025_2024-12-21.csv

fanmatch

kenpom_predictions_2024-12-21.csv

fourfactors

kenpom_fourfactors_2025.csv

pointdist

kenpom_pointdist_2025.csv

height

kenpom_height_2025.csv

miscstats

kenpom_miscstats_2025.csv

archive

kenpom_archive_2024-12-21.csv

Each command exports three formats: .csv, .json, and .parquet

Configuration

Set in .env:

Variable

Required

Default

Description

KENPOM_API_KEY

Yes

-

Your KenPom API key

KENPOM_RATE_LIMIT_RPS

No

2.0

Requests per second

KENPOM_CACHE_TTL_SECONDS

No

21600

Cache TTL (6 hours)

KENPOM_MAX_RETRIES

No

5

Max retry attempts

KENPOM_OUT_DIR

No

data

Output directory

OV_CUSTOMER_ID

For odds

-

overtime.ag customer ID

OV_PASSWORD

For odds

-

overtime.ag password

Automated Odds Fetching

The project includes automated scraping of real market odds from overtime.ag for NCAA Basketball games.

Setup

  1. Install Playwright browser:

    uv run playwright install chromium
  2. Add credentials to .env:

    OV_CUSTOMER_ID=your_customer_id
    OV_PASSWORD=your_password
    KENPOM_API_KEY=your_kenpom_api_key

Manual Usage

Fetch current odds and generate predictions:

uv run fetch-odds

This will:

  1. Scrape NCAA Basketball odds from overtime.ag

  2. Save odds to CSV in data/ directory

  3. Automatically generate game predictions using KenPom data

Automated Workflows

A GitHub Actions workflow is available at .github/workflows/odds_workflow.yaml that:

  • Runs daily at 4:00 AM PST (12:00 PM UTC)

  • Fetches odds from overtime.ag

  • Generates KenPom predictions

  • Calculates betting edge

  • Uploads results as artifacts

Setup:

  1. Add GitHub Secrets:

    • OV_CUSTOMER_ID - overtime.ag customer ID

    • OV_PASSWORD - overtime.ag password

    • KENPOM_API_KEY - KenPom API key

  2. The workflow runs automatically on schedule or can be triggered manually via workflow_dispatch

View results:

  • Go to Actions tab in GitHub repository

  • Download artifacts from completed workflow runs

Option 2: Windows Task Scheduler (Local)

For local Windows machines, set up Task Scheduler (runs daily at 4:00 AM PST):

powershell -File setup_task_xml.ps1

The scheduled task runs with automatic retry logic:

  • Retries every 10 minutes if odds not yet available

  • Stops after 2 hours or successful fetch

  • Logs all activity to logs/odds_fetch.log

View logs:

Get-Content logs\odds_fetch.log -Tail 50

Manage task:

# Check status
schtasks /query /tn "FetchOvertimeCollegeBasketballOdds" /fo LIST

# Run manually
Start-ScheduledTask -TaskName 'FetchOvertimeCollegeBasketballOdds'

# Stop task
Stop-ScheduledTask -TaskName 'FetchOvertimeCollegeBasketballOdds'

# Delete task
schtasks /delete /tn "FetchOvertimeCollegeBasketballOdds" /f

See docs/ODDS_WORKFLOW.md for complete documentation.

Project Structure

kenpom-client/
├── src/kenpom_client/
│   ├── mcp_server.py         # MCP server (11 tools)
│   ├── client.py             # API wrapper
│   ├── cli.py                # Command-line interface
│   ├── overtime_scraper.py   # overtime.ag odds scraper
│   ├── models.py             # Pydantic models
│   ├── config.py             # Settings
│   ├── cache.py              # File-based caching
│   ├── http.py               # Rate limiting & retries
│   └── exceptions.py         # Custom exceptions
├── docs/                     # API documentation
│   ├── _index.md             # Documentation index
│   ├── ratings.md            # Ratings endpoint
│   ├── ratings_archive.md    # Archive endpoint
│   ├── fanmatch.md           # FanMatch endpoint
│   ├── four_factors.md       # Four Factors endpoint
│   ├── height.md             # Height endpoint
│   ├── misc_stats.md         # Misc Stats endpoint
│   ├── point_distribution.md # Point Distribution endpoint
│   ├── teams.md              # Teams endpoint
│   ├── conferences.md        # Conferences endpoint
│   ├── ODDS_WORKFLOW.md      # Automated odds fetching guide
│   └── DAILY_SLATE_API.md    # Daily slate output contract
├── schemas/                  # JSON Schemas
│   ├── ratings.schema.json
│   ├── ratings_archive.schema.json
│   ├── fanmatch.schema.json
│   ├── four_factors.schema.json
│   ├── height.schema.json
│   ├── misc_stats.schema.json
│   ├── point_distribution.schema.json
│   ├── teams.schema.json
│   ├── conferences.schema.json
│   ├── daily_slate_row.json
│   └── daily_slate_table.json
├── fetch_odds_scheduled.bat  # Windows scheduled task script
├── setup_task_xml.ps1        # Task Scheduler setup
├── .mcp.json                 # MCP server configuration
├── data/                     # Output directory (gitignored)
├── logs/                     # Task logs (gitignored)
├── .cache/                   # API cache (gitignored)
└── .env                      # API keys (gitignored)

Programmatic Usage

from kenpom_client.client import KenPomClient
from kenpom_client.config import Settings

settings = Settings.from_env()
client = KenPomClient(settings)

# Get ratings
ratings = client.ratings(y=2025)
for team in ratings[:5]:
    print(f"{team.TeamName}: AdjEM {team.AdjEM}")

# Get predictions
games = client.fanmatch(d="2024-12-21")
for game in games:
    spread = game.HomePred - game.VisitorPred
    print(f"{game.Visitor} @ {game.Home}: {spread:+.1f}")

# Compare teams
four_factors = client.four_factors(y=2025)
height_data = client.height(y=2025)
misc_stats = client.misc_stats(y=2025)

client.close()

API Endpoints Reference

Endpoint

Method

Description

Ratings

ratings(y, team_id, c)

Current season efficiency ratings

Archive

archive(d, preseason, y)

Historical point-in-time ratings

Four Factors

four_factors(y)

eFG%, TO%, OR%, FT Rate

Point Dist

point_distribution(y)

Scoring breakdown by shot type

Height

height(y)

Height, experience, continuity

Misc Stats

misc_stats(y)

Shooting %, blocks, steals, assists

FanMatch

fanmatch(d)

Game predictions and spreads

Teams

teams(y, c)

Team rosters with arena info

Conferences

conferences(y)

Conference metadata

Documentation

Full API documentation and JSON schemas are available in the docs/ and schemas/ directories.

API Endpoints: See docs/_index.md for the complete documentation index.

Workflows & Contracts:

Document

Description

ODDS_WORKFLOW.md

Automated odds fetching workflow

WORKFLOW_MONITORING.md

GitHub Actions workflow monitoring guide

DAILY_SLATE_API.md

Daily slate output contract

daily_slate_row.json

JSON Schema: single prediction

daily_slate_table.json

JSON Schema: prediction array

Development:

Document

Description

RUN_TESTS.md

Guide for running the test suite

Development

Automated Validation Hooks

This project uses automated hooks for quality assurance:

  • Pre-commit hook - Validates code before commits (format, lint, type check, tests)

  • Post-edit hook - Type checks after Claude edits files

  • Session start hook - Syncs dependencies on session start

See HOOKS.md for complete documentation.

Manual Commands

uv run ruff format .      # Format
uv run ruff check .       # Lint
pyrefly check             # Type check
uv run pytest             # Test

# Full validation (what pre-commit runs)
powershell -ExecutionPolicy Bypass -File scripts/hooks/validate-all.ps1

Available Tools

15 tools
classify_effortA

Classify a query's effort level for dynamic model routing. Returns recommended effort level (low/medium/high), model hint, and thinking budget. Use this to determine appropriate reasoning depth before executing complex tasks.

Inputs: query (required).

get_tool_effortB

Get the effort level metadata for a specific tool. Returns the tool's default effort level and whether it requires reasoning.

Inputs: tool_name (required).

kenpom_archiveA

Get historical ratings from a specific past date. Use this for backtesting or historical analysis.

Inputs: archive_date (required).

kenpom_conferencesB

Get list of conferences for a season.

Inputs: season (required).

kenpom_fourfactorsB

Get Four Factors data: eFG%, TO%, OR%, FT Rate for offense and defense. These are the key stats that determine game outcomes.

Inputs: season (required), team.

kenpom_heightB

Get height, experience, and roster continuity data for teams.

Inputs: season (required), team.

kenpom_matchupA

Compare two teams head-to-head with key metrics side by side. Great for analyzing upcoming games.

Inputs: team1 (required), team2 (required), season.

kenpom_miscstatsB

Get miscellaneous stats: shooting percentages, block/steal rates, assist rates, 3-point attempt rates.

Inputs: season (required), team.

kenpom_pointdistB

Get point distribution data: percentage of points from FTs, 2-pointers, and 3-pointers for offense and defense.

Inputs: season (required), team.

kenpom_predictionsB

Get KenPom game predictions (FanMatch) for a specific date. Includes predicted scores, win probability, and spread.

Inputs: game_date.

kenpom_projectC

Project game score, margin, total, and win probability for a matchup. Uses OE/DE crossover method with configurable home court advantage.

Inputs: home_team (required), visitor_team (required), k, season, +2 more.

kenpom_ratingsB

Get current efficiency ratings (AdjOE, AdjDE, AdjEM) for all teams. This is the core KenPom ranking data.

Inputs: season (required), team.

kenpom_slateB

Build full projection slate table for a date. Returns all games with projected scores, margins, win probabilities, and optional market odds. Use backtest=true for time-correct archive features.

Inputs: k, backtest, home_adv, game_date, +1 more.

kenpom_teamsB

Get team rosters with coach, arena, and conference info for a season.

Inputs: season (required), team.

kenpom_top_teamsB

Get top N teams by a specific metric (AdjEM, AdjOE, AdjDE, etc.)

Inputs: metric (required), count, season.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have distinct purposes like ratings, predictions, or team rosters. However, 'kenpom_predictions' and 'kenpom_project' and 'kenpom_slate' overlap slightly in providing game forecasts, and the two effort-classification tools are unrelated to basketball data, causing potential confusion.

    Naming Consistency3/5

    Thirteen tools follow the 'kenpom_' prefix with noun-based names, but 'classify_effort' and 'get_tool_effort' break the pattern. Some compound names lack underscores (e.g., 'fourfactors', 'miscstats') while others use them, creating minor inconsistency.

    Tool Count5/5

    With 15 tools covering ratings, four factors, predictions, rosters, and more, the count is well-scoped for a college basketball analytics server. Each tool serves a clear function without redundancy.

    Completeness4/5

    The tool set covers core KenPom data like efficiency ratings, four factors, and game predictions. Missing are raw game results or player-level stats, but for team-level analysis the surface is nearly complete.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server providing access to college football statistics sourced from the College Football Data API within Claude Desktop.
      9
      27
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for accessing college basketball statistics through the SportsData.io CBB v3 Stats API, enabling AI agents to retrieve and analyze college basketball data through natural language interactions.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A general-purpose MCP server with utility tools including datetime information, safe math calculations, text statistics, JSON extraction, knowledge base search, and HTTP GET requests. It demonstrates server-side MCP implementation and can be connected to Claude Desktop or LangGraph agents.
      MIT