Sleeper MCP
A lightweight FastAPI server that exposes Sleeper API data and richer matchup/player summaries for use as a Model Context
Protocol (MCP) tool. Run it locally, expose it with ngrok, and connect it to ChatGPT to fetch league data, standings context,
and weekly reports.
Features
- Proxy endpoints for common Sleeper resources (users, leagues, rosters, matchups, user leagues).
- Weekly matchup summaries that group scores by matchup with owner names, winners, margins, and top/low scorers.
- Week-specific player leaderboards with position/availability filters for waiver-wire scanning.
- Health endpoint to verify connectivity when tunneling through ngrok.
Getting started
-
Install dependencies (preferably inside a virtual environment):
bash python -m pip install -r requirements.txt -
Run the MCP server locally:
bash uvicorn app:app --host 0.0.0.0 --port 8000 -
Expose the server with ngrok:
bash ngrok http 8000
Copy the forwarded HTTPS URL (e.g.,https://abcd1234.ngrok.io). -
Register the MCP endpoint in ChatGPT:
- In ChatGPT, add a new MCP and provide the ngrok HTTPS URL.
- Use the/healthendpoint for initial validation.
Available endpoints
GET /health— quick readiness check.GET /api/users/{username}— retrieve a Sleeper user by username or user ID.GET /api/users/{username}/leagues/{season}— all NFL leagues for a user in a given season.GET /api/users/{username}/weekly-report/{season}/{week}— weekly reports for all of a user's leagues.GET /api/leagues/{league_id}— fetch league metadata.GET /api/leagues/{league_id}/users— list users in a league.GET /api/leagues/{league_id}/rosters— list rosters in a league.GET /api/leagues/{league_id}/matchups/{week}— raw matchup data for a given week.GET /api/leagues/{league_id}/weekly-report/{week}— grouped matchup summaries with owner names, winners, and margins.GET /api/leagues/{league_id}/top-players/{week}?position=RB&availability=available&limit=15— weekly fantasy leaderboard
filtered by position and whether players are available on the waiver wire (availability can beall,available, or
unavailable).
Username-only onboarding: All user-scoped endpoints take a Sleeper username (or user ID) as the path parameter and
resolve the underlying user_id for you. To start, provide only your Sleeper username—no separate IDs are required for
weekly reports or league lookups.
Example usage
Weekly report for week 3 of a league:```bash
curl "http://localhost:8000/api/leagues/123456789/weekly-report/3"
Weekly leaderboard of waiver-wire RBs in week 5:```bash
curl "http://localhost:8000/api/leagues/123456789/top-players/5?position=RB&availability=available&limit=20"
All week-2 reports for every league managed by a user in 2024:bash
curl "http://localhost:8000/api/users/example_username/weekly-report/2024/2"
Implementation notes
- Server: FastAPI serves a thin MCP-friendly REST surface for ChatGPT. Each endpoint opens a short-lived
SleeperClient
(httpx-based) to call Sleeper's public API and returns JSON designed for summarization. - Reporting helpers (
reports.py): summarize_weekly_matchupsgroups matchups, annotates owner names, captures winners/losers, and surfaces top/low scorers
to simplify "week in review" prompts.top_weekly_playersuses weekly stats plus league rosters to flag waiver-wire availability and filter by position.user_weekly_reportresolves a user and fetches reports for every NFL league in a season, enabling quick personal recaps.- Sleeper client (
sleeper_client.py): small httpx wrapper around Sleeper endpoints for users, leagues, rosters, matchups,
weekly stats, player metadata, and user leagues.
These helpers are tailored to common MCP prompts: weekly waiver-wire scans, per-user league recaps, and matchup/standings
storylines (winners, margins, top/low scores).
