Sleeper Fantasy Football MCP
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., "@Sleeper Fantasy Football MCP Compare all rosters in my league and identify the three weakest players on my team"
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.
Sleeper Fantasy Football MCP
A local, read-only Model Context Protocol server that gives ChatGPT desktop and Codex fresh context from Sleeper fantasy-football leagues.
The server is designed for questions such as:
Is this dynasty roster ready to contend?
Which players should I cut before the draft?
How does a proposed trade affect both teams?
Who owns each future rookie pick?
What trades and waiver moves happened recently?
How do all rosters in the league compare?
It uses Sleeper's public API. No Sleeper password, API key, session cookie, or account token is required.
Capabilities
The MCP server can retrieve:
Sleeper account identity and current NFL state
Leagues for a selected season
League settings, scoring, lineup slots, records, and owners
Your roster or every roster, with player IDs resolved to names
Starters, bench, reserve, taxi squad, and keepers
Future draft-pick ownership and traded picks
Focused context for evaluating a proposed trade
Completed trades, waivers, and free-agent transactions
Weekly matchups and lineups
Live or completed draft boards
Trending additions and drops
Player-name search
Related MCP server: Sleeper Draft Assistant MCP
Important limitation
Sleeper's documented public API does not expose the private inbox containing unaccepted incoming or outgoing trade proposals. Paste or screenshot the offer itself; the MCP can then pull the live league rules, both rosters, records, and draft-pick inventories needed to analyze it.
This project cannot send, accept, reject, or cancel trades. It deliberately avoids unofficial authenticated endpoints and Sleeper session tokens.
Requirements
macOS, Linux, or Windows with a compatible MCP host
Node.js 20 or newer
npm
A Sleeper username
ChatGPT desktop, Codex CLI, or another STDIO-capable MCP client
Quick start
Clone or download the repository, then run:
cd /path/to/sleeper-fantasy-mcp
chmod +x scripts/*.sh
./scripts/setup-mac.sh YOUR_SLEEPER_USERNAMEThe setup helper:
Checks Node.js and npm.
Installs dependencies.
Runs local syntax and unit tests.
Verifies the Sleeper username.
Lists the current-season leagues it finds.
Prints the exact local MCP command and environment variable.
A Sleeper username can change. The setup output also shows the stable Sleeper user ID, which can be supplied through SLEEPER_USER_ID instead.
Connect to ChatGPT desktop
Open Settings → MCP servers → Add server and enter:
Name:
SleeperTransport:
STDIOCommand: the absolute Node path printed by the setup script
Arguments: the absolute
src/index.jspath printed by the setup scriptEnvironment:
SLEEPER_USERNAME=YOUR_SLEEPER_USERNAME
Save the server and restart ChatGPT desktop. Type /mcp in the composer to verify that the server and its tools are available.
Use absolute paths. A macOS desktop application does not always inherit the same shell PATH as Terminal.
Connect to Codex
The setup script prints a command tailored to the current machine. You can also run:
./scripts/add-to-codex.sh YOUR_SLEEPER_USERNAMEThe equivalent manual command is:
codex mcp add sleeper \
--env SLEEPER_USERNAME=YOUR_SLEEPER_USERNAME \
-- /absolute/path/to/node /absolute/path/to/sleeper-fantasy-mcp/src/index.js
codex mcp listCodex stores local MCP configuration under ~/.codex/config.toml. Do not commit that file to this repository.
Test with MCP Inspector
After installing dependencies:
SLEEPER_USERNAME=YOUR_SLEEPER_USERNAME npm run inspectThe Inspector launches a local client that can list and invoke each tool directly.
Example prompts
Use Sleeper to list all of my 2026 leagues and identify which are dynasty, keeper, or redraft.
Pull my roster and league settings for SHADynasty. Assess whether the roster is ready to contend this season.
In my DFB league, compare every roster and identify the three weakest players on my team.
Pull trade context for my team and the other owner's team, then assess this proposal: [paste offer].
Show the most recent completed trades in this league and explain which teams improved most.
Pull the current draft board and identify my biggest roster needs before my next pick.
Tool reference
Tool | Purpose |
| Resolve the configured Sleeper account and current NFL state. |
| List leagues for a season and identify the user's roster ID. |
| Fetch rules, scoring, teams, records, drafts, and pick ownership. |
| Fetch the user's roster, lineup groups, and draft picks. |
| Fetch every roster for league-wide comparison. |
| Fetch focused roster, rule, record, and pick context for selected teams. |
| Fetch trades, waivers, and free-agent moves by week range. |
| Fetch one week's matchups, starters, bench, and points. |
| Fetch draft settings, order, picks, and traded slots. |
| Resolve player names to Sleeper player records. |
| Fetch frequently added or dropped players. |
Configuration
Environment variable | Required | Description |
| Yes, unless using | Sleeper username used to locate the account. |
| Optional | Stable user ID; takes precedence over the username. |
| Optional | Four-digit season used when a tool does not provide one. |
| Optional | Override the local directory for the public player cache. |
Freshness and caching
League settings, rosters, transactions, matchups, drafts, and picks are requested from Sleeper when a tool is called. There is no background synchronization process.
Sleeper's full NFL player directory is much larger, so it is cached for 24 hours at:
~/.cache/sleeper-fantasy-mcp/players-nfl.jsonDelete that file to force a refresh on the next player-dependent request.
Privacy and security
The server is read-only.
It sends network requests only to
https://api.sleeper.app/v1.It does not collect a Sleeper password or authenticated account token.
The only local data it writes is Sleeper's public NFL player directory cache.
League names, usernames, team names, and all other Sleeper-returned text are treated as untrusted data rather than model instructions.
Raw Sleeper metadata objects are not forwarded unless a known field is required for a feature.
Review SECURITY.md before expanding the server's permissions or endpoints.
Development
Install dependencies and run all local checks:
npm install
npm run checkThe first npm install creates package-lock.json. Review and commit that lockfile so subsequent local and CI installs resolve the same dependency graph.
Run only the live connection check:
npm run check:connection -- YOUR_SLEEPER_USERNAMEStart the STDIO server manually:
SLEEPER_USERNAME=YOUR_SLEEPER_USERNAME npm startThe process will appear to wait. That is expected: an STDIO MCP server listens for JSON-RPC requests from its host. Stop it with Ctrl+C.
Never use console.log in the server process. STDOUT is the MCP protocol channel; diagnostics belong on STDERR through console.error.
Project structure
.
├── .github/ # CI and dependency updates
├── scripts/ # Setup, Codex registration, and connection check
├── src/
│ ├── index.js # MCP server and tool definitions
│ └── sleeper-client.js # Sleeper API client and response shaping
├── test/ # Offline unit tests
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE
└── README.mdTroubleshooting
No Sleeper account is configured
Add SLEEPER_USERNAME or SLEEPER_USER_ID to the MCP server environment, then restart the host.
ChatGPT or Codex cannot find node
Run:
which nodeUse that complete path as the MCP command.
The server starts and appears to hang
That is normal when started manually. It is waiting for an MCP client on stdin.
A renamed Sleeper username no longer resolves
Update SLEEPER_USERNAME, or use the stable SLEEPER_USER_ID printed by the connection check.
Player information appears stale
Delete the cached player file:
rm ~/.cache/sleeper-fantasy-mcp/players-nfl.jsonThe next player-dependent request will download a new copy.
Contributing
See CONTRIBUTING.md. Changes should preserve the read-only security boundary and use only documented public Sleeper endpoints.
License
MIT. See LICENSE.
Disclaimer
This is an independent project and is not affiliated with, endorsed by, or sponsored by Sleeper.
Available Tools
11 toolssleeper_accountSleeper accountBRead-only
Resolve the configured Sleeper username to its stable user ID and return the current NFL state.
Inputs: username.
sleeper_all_rostersAll Sleeper rostersARead-only
Get every team’s live roster in a league with player names, positions, teams, injury status, records, FAAB, and lineup grouping. Useful for league-wide comparisons.
Inputs: league_id (required).
sleeper_draft_boardSleeper draft boardARead-only
Get a live or completed draft board, resolved player picks, draft order, and traded draft slots. Provide a league ID to use its newest draft, or a specific draft ID.
Inputs: draft_id, league_id, draft_season.
sleeper_league_overviewSleeper league overviewARead-only
Get league rules, scoring, lineup slots, team directory, records, drafts, traded picks, and calculated future pick ownership. Does not include every player on every roster.
Inputs: league_id (required), username, pick_years.
sleeper_list_leaguesList Sleeper leaguesARead-only
List the configured user’s NFL leagues for a season. Use this first to map league names to league IDs.
Inputs: season, username, include_roster_ids.
sleeper_matchupsSleeper matchupsARead-only
Get one league week’s matchups with resolved starters, bench players, lineup slots, and current points.
Inputs: league_id (required), week.
sleeper_my_rosterMy Sleeper rosterARead-only
Get the configured user’s live roster in one league, resolved to player names and grouped into starters, bench, reserve, taxi, and keepers, plus draft-pick ownership.
Inputs: league_id (required), username.
sleeper_search_playersSearch Sleeper playersARead-only
Search Sleeper’s player directory by name and optionally position. Useful for resolving names mentioned in a proposed trade.
Inputs: query (required), limit, position, active_only.
sleeper_trade_contextSleeper trade contextARead-only
Get focused trade-analysis context for selected teams: full rosters, league rules, records, and future pick inventories. Teams can be identified by roster ID, owner name, username, or team name. Pending private trade offers are not exposed by the official API, so the offer itself must be pasted or described.
Inputs: league_id (required), username, pick_years, team_queries.
sleeper_transactionsSleeper transactionsARead-only
Get and resolve completed or pending transaction records—trades, waivers, and free-agent moves—for a league and week range. Defaults to the current week and previous three weeks.
Inputs: league_id (required), types, status, end_week, +1 more.
sleeper_trending_playersSleeper trending playersARead-only
Get players most frequently added or dropped on Sleeper over a recent time window.
Inputs: type, limit, lookback_hours.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource or workflow, from account resolution to rosters, transactions, matchups, and drafts. A few tools overlap in raw data—like all_rosters, my_roster, and trade_context all exposing roster info—but their scopes are clearly differentiated by descriptions.
All tools share the consistent 'sleeper_' prefix and use snake_case, making the namespace predictable. Naming style varies between verb-led (list_leagues, search_players) and noun-led (account, transactions, matchups), but the pattern is still coherent and readable.
Eleven tools is a well-scoped count for a fantasy football data server. Each tool covers a meaningful slice of the domain—leagues, rosters, trades, transactions, matchups, drafts, and player discovery—without unnecessary duplication.
The toolset comprehensively covers the read-only Sleeper fantasy football domain: account identity, leagues, rosters, trade context, transactions, matchups, drafts, and player search/trending. There are no obvious dead ends for typical fantasy football analysis workflows.
Maintenance
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Sleeper fantasy football leagues, enabling team snapshots, available players, matchups, trade context, and league history through standardized MCP tools.MIT
- FlicenseNot gradedqualityCmaintenanceProvides read-only, league-aware Sleeper fantasy football draft context to AI assistants, including live picks, rosters, and player availability over Streamable HTTP MCP.-
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server that provides access to public Sleeper NFL fantasy data, including leagues, rosters, matchups, waivers, drafts, and player information. It enables AI clients to retrieve fantasy football details without requiring authentication or account modifications.-
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to Sleeper fantasy football data including user info, leagues, rosters, matchups, and NFL state through MCP tools.-