kenpom
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kenpom Show me the top 10 teams by adjusted efficiency margin."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_KEYMCP 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 |
| Current efficiency ratings (AdjOE, AdjDE, AdjEM) |
| Game predictions with spreads and win probability |
| Head-to-head comparison of two teams |
| Top N teams by any metric |
| Four Factors analytics (eFG%, TO%, OR%, FT Rate) |
| Point distribution (% from FT, 2P, 3P) |
| Height, experience, and continuity |
| Shooting %, blocks, steals, assists |
| Team rosters with coach and arena |
| Conference list |
| 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-oddsOutput File Naming
All files follow: kenpom_{data_type}_{identifiers}.{ext}
Command | Example Output |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Each command exports three formats: .csv, .json, and .parquet
Configuration
Set in .env:
Variable | Required | Default | Description |
| Yes | - | Your KenPom API key |
| No |
| Requests per second |
| No |
| Cache TTL (6 hours) |
| No |
| Max retry attempts |
| No |
| Output directory |
| For odds | - | overtime.ag customer ID |
| 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
Install Playwright browser:
uv run playwright install chromiumAdd 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-oddsThis will:
Scrape NCAA Basketball odds from overtime.ag
Save odds to CSV in
data/directoryAutomatically generate game predictions using KenPom data
Automated Workflows
Option 1: GitHub Actions (Recommended for CI/CD)
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:
Add GitHub Secrets:
OV_CUSTOMER_ID- overtime.ag customer IDOV_PASSWORD- overtime.ag passwordKENPOM_API_KEY- KenPom API key
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.ps1The 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 50Manage 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" /fSee 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 |
| Current season efficiency ratings |
Archive |
| Historical point-in-time ratings |
Four Factors |
| eFG%, TO%, OR%, FT Rate |
Point Dist |
| Scoring breakdown by shot type |
Height |
| Height, experience, continuity |
Misc Stats |
| Shooting %, blocks, steals, assists |
FanMatch |
| Game predictions and spreads |
Teams |
| Team rosters with arena info |
Conferences |
| 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.
Endpoint | Docs | Schema |
Ratings | ||
Archive | ||
FanMatch | ||
Four Factors | ||
Height | ||
Misc Stats | ||
Point Dist | ||
Teams | ||
Conferences |
Workflows & Contracts:
Document | Description |
Automated odds fetching workflow | |
GitHub Actions workflow monitoring guide | |
Daily slate output contract | |
JSON Schema: single prediction | |
JSON Schema: prediction array |
Development:
Document | Description |
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.ps1Available Tools
15 toolsclassify_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
Scored across 15 tools
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.
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.
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.
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
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server providing access to college football statistics sourced from the College Football Data API within Claude Desktop.927MIT
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseCqualityDmaintenanceA Model Context Protocol (MCP) server that demonstrates how to build and implement custom tools for Claude using the mcp-framework.10ISC
- AlicenseNot gradedqualityDmaintenanceA 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