sleeper-mcp

A Model Context Protocol server for Sleeper fantasy football, built so an AI assistant can actually answer fantasy questions instead of handing you a wall of player IDs.

Ask Claude, Cursor, or any MCP client things like:

• "Who should I start this week in my dynasty league?"
• "Show me the standings and who's on the waiver wire at RB."
• "Was the Bijan-for-Chase trade fair? Who won it?"
• "Who did I draft in round 1 the last three years?"
• "Am I going to win this week? What are my playoff odds, and how many wins do I need?"
• "Would trading for Justin Jefferson actually raise my playoff odds? What about picking up a backup RB?"
• "Are any of my lineups broken this week?" (one check across all your leagues: empty slots, byes, players ruled out)
• "Move Jacobs to IR, start Corum, and put a claim in for Kaelon Black." (with a Sleeper session, see Account tools)

No login, no API key for reads: Sleeper's public API covers everything above the "Account" line. Add your Sleeper session and the same server can also set lineups, manage IR/taxi, submit waiver claims and propose trades.

Why another Sleeper MCP?

There are several community Sleeper MCP servers. This one focuses on the things that make the difference between "it works" and "it's useful in a conversation":

| | sleeper-mcp (this) | typical alternatives | | --- | --- | --- | | Player IDs resolved to names/positions/teams/injury flags in every response | ✅ everywhere (rosters, matchups, transactions, drafts, brackets) | usually raw IDs, or names only in one or two tools | | Roster IDs resolved to team + manager names | ✅ | rarely | | Computed standings (rank, record, PF/PA, streak, FAAB left, divisions) | ✅ | raw roster settings | | Matchups paired with per-player points and margins | ✅ | raw matchup arrays | | Trades summarized as "gave / got" per side, picks and FAAB included | ✅ | raw adds/drops maps | | Free agents for a league (unrostered, ranked, trending-annotated) | ✅ | ❌ | | Projections & stats scored with the league's exact scoring settings | ✅ | ❌ (or PPR only) | | Start/sit: optimal lineup with slot eligibility (FLEX, SUPER_FLEX, IDP) | ✅ | ❌ | | Live win probability, Monte Carlo playoff odds and trade/waiver what-ifs over the real schedule, under league scoring | ✅ | rare | | League history across seasons with champions | ✅ | ❌ | | Select a team by username, user_id, roster_id or team name | ✅ | user_id / roster_id only | | "Current week/season" defaults from Sleeper's NFL state | ✅ | manual | | Transports | stdio and Streamable HTTP (stateless, bearer auth, CORS, health check, Docker) | stdio only | | Player database (~5 MB) | memory + disk cache, daily refresh, stale-cache fallback | re-downloaded per process | | Rate limiting / retries | 600 req/min budget, backoff on 429/5xx, in-flight de-dup | none | | Tests | 100+ unit + integration tests (in-memory and HTTP transports) plus a live smoke test | varies | | Tool annotations, structuredContent, prompts, resources | ✅ | partial |

The 28 read tools need no login. They use Sleeper by default; optional injury context can add ESPN reports. The 11 account tools (2 private reads, 9 writes) are registered only when you configure a Sleeper session, and --read-only keeps the writes off even then.

Quick start

Requires Git, Node.js 20+ and npm. Install from source; this project is not currently distributed on npm. npm is used below to install dependencies and build the local server, not to download a published @joscaz/sleeper-mcp package.

git clone https://github.com/joscaz/sleeper-mcp.git
cd sleeper-mcp
npm ci
npm run build
node dist/index.js --help

Keep the checkout: MCP clients launch its built dist/index.js. Replace /absolute/path/to/sleeper-mcp in the examples with its actual location. Use the full path to node too if your desktop client cannot find it on PATH. On Windows, use a path such as C:/Users/you/sleeper-mcp/dist/index.js.

The examples use --read-only, so they cannot change your account even if session credentials are present. To enable account changes deliberately, see Account tools.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "sleeper": {
      "command": "node",
      "args": ["/absolute/path/to/sleeper-mcp/dist/index.js", "--read-only"],
      "env": { "SLEEPER_USERNAME": "your_sleeper_username" }
    }
  }
}

Claude Code

claude mcp add sleeper -e SLEEPER_USERNAME=your_sleeper_username -- node /absolute/path/to/sleeper-mcp/dist/index.js --read-only

Cursor / Windsurf / other stdio clients

Same shape: command node, args ["/absolute/path/to/sleeper-mcp/dist/index.js", "--read-only"], env SLEEPER_USERNAME.

Updating your checkout

From a clean checkout on the branch you want to follow:

git pull --ff-only
npm ci
npm run build

Restart your MCP client afterwards. If you have local changes or a detached release tag, choose how to preserve or update those before pulling.

Make it yours

Sleeper's API is public and read-only, so there is no login step: every league, roster and matchup is readable by anyone who knows a username or league ID. The only thing the server cannot know by itself is who you are. Set SLEEPER_USERNAME (or pass --user) and every tool that takes a user or team falls back to you, so "what are my leagues?", "show my roster" and "who should I start?" work without naming yourself. Explicit selectors always win, so questions about other managers still work.

Remote / hosted (Streamable HTTP)

node dist/index.js --http --host 127.0.0.1 --port 3000 --read-only
# MCP endpoint:  http://localhost:3000/mcp   (POST, JSON-RPC)
# Health check:  http://localhost:3000/healthz

This example listens only on your own machine. For remote hosting, configure SLEEPER_MCP_AUTH_TOKEN through your host's secret manager, use --host 0.0.0.0, and put HTTPS in front of the service. Configure the same bearer credential securely in your MCP client. Not every remote MCP client supports static bearer authentication; check your client's requirements.

When a Sleeper session is configured with write tools enabled, the bearer token is mandatory unless the server is bound to loopback: anyone who can reach an unauthenticated /mcp could otherwise change your lineups, drop players and send trades. The server refuses to start in that configuration unless the explicit insecure override is set. Bearer authentication is also recommended for remote read-only account access, which can expose private pending transactions. See SECURITY.md.

Build Docker locally from the checkout; no published container image is required. With SLEEPER_MCP_AUTH_TOKEN already set securely in your environment:

docker build -t sleeper-mcp .
docker run --rm -p 127.0.0.1:3000:3000 -e SLEEPER_MCP_AUTH_TOKEN -v sleeper-cache:/data sleeper-mcp node dist/index.js --http --read-only

The port is exposed only to the host by default. Use your hosting platform's private ingress or HTTPS configuration for remote access. Neither command publishes an image.

Tools

Every tool that takes a team accepts any of username (or display name), user_id, roster_id, team_name (partial, case-insensitive), team (any of those names in one field, when you are not sure which kind you have), or nothing at all when SLEEPER_USERNAME is set. week defaults to the current NFL week and season to the current league season.

Users & leagues

| Tool | What it returns | | --- | --- | | get_nfl_state | Current season, season_type, week, league_season. | | get_user | Username ↔ user_id, display name, avatar. | | get_user_leagues | A user's leagues for a season with league_id, scoring format, roster shape, status. | | get_league | Summarized settings: scoring (PPR/half/std, TE premium, pass TD, bonuses), roster slots, redraft/keeper/dynasty, waivers/FAAB, playoffs, trade deadline, divisions, commissioners. include_raw for the full objects. | | get_league_standings | Ranked standings with record, PF/PA, streak, waiver position, FAAB remaining, division. Doubles as the roster_id → manager map. | | get_league_history | Walks previous_league_id back through seasons: champion, runner-up, regular-season leader, points leader. |

Rosters & matchups

| Tool | What it returns | | --- | --- | | get_roster | One team: current weekly starters during an active season, labeled with slots (QB, RB, FLEX…), plus bench, IR, taxi, record, FAAB. Uses live weekly starters with a session; otherwise public matchup data, which can lag. | | get_league_rosters | Every roster in the league, including roster-default starters (include_bench=false for a lighter payload). Use get_matchups for weekly scoring lineups. | | get_matchups | Paired matchups for a week with scores, margin, leader, starters with per-player points (include_bench for bench points). Filter to one team. | | get_playoff_bracket | Winners/losers bracket with round labels ("Championship", "Semifinal", "Toilet bowl final"), teams and results. |

Transactions & picks

| Tool | What it returns | | --- | --- | | get_transactions | Trades, waivers, free-agent moves with players, teams, FAAB bids, traded picks and a per-side trade_summary. Current week or all_weeks. Failed claims hidden unless status="failed"/"all". | | get_traded_picks | All traded picks grouped by current owner with original/previous owners. |

Drafts

| Tool | What it returns | | --- | --- | | get_drafts | Drafts for a league or for a user + season. | | get_draft | Draft settings and the resolved draft order (slot → manager → roster). | | get_draft_picks | Every pick with player, position, overall/round pick, drafter, keeper flag, auction price. Filter by round or team. |

Players

| Tool | What it returns | | --- | --- | | search_players | Name search (handles "ja marr", "lions") with position/team filters, injury and depth-chart info. | | get_player | Full profile plus sourced injury context: report/retrieval timestamps, cache expiry, stale flags, and disagreements. Existing profile fields remain Sleeper-based. | | get_injury_report | Current injury context for a roster (league_id + team selector) or up to 100 player_ids. Shows each source, timestamps, links, and a needs_check flag; never assumes a missing report means healthy. | | get_trending_players | Most added/dropped players platform-wide over the last N hours. | | get_free_agents | Unrostered players in a league ranked by Sleeper's player rank, annotated with 24h trending adds. In season, flags players who can't be picked up right now (availability: locked once their game has kicked off, on_waivers after a recent drop); addable_only hides them. |

Projections & stats

| Tool | What it returns | | --- | --- | | get_projections | Weekly or season (week=0) projections. Filter by players/position/league/team. scoring="league" applies the league's exact scoring_settings. | | get_player_stats | Actual weekly/season fantasy production with the same filters and scoring options. | | get_lineup_projections | Start/sit for one team: current vs optimal lineup (respecting FLEX/SUPER_FLEX/IDP eligibility), suggested swaps, bye/injury/empty-slot warnings. Once games kick off, players whose game has started stay locked and count the points they have scored (