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

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_USERNAME

The setup helper:

1. Checks Node.js and npm.
2. Installs dependencies.
3. Runs local syntax and unit tests.
4. Verifies the Sleeper username.
5. Lists the current-season leagues it finds.
6. 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: Sleeper
• Transport: STDIO
• Command: the absolute Node path printed by the setup script
• Arguments: the absolute src/index.js path printed by the setup script
• Environment: 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_USERNAME

The 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 list

Codex 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 inspect

The 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
sleeper_account	Resolve the configured Sleeper account and current NFL state.
sleeper_list_leagues	List leagues for a season and identify the user's roster ID.
sleeper_league_overview	Fetch rules, scoring, teams, records, drafts, and pick ownership.
sleeper_my_roster	Fetch the user's roster, lineup groups, and draft picks.
sleeper_all_rosters	Fetch every roster for league-wide comparison.
sleeper_trade_context	Fetch focused roster, rule, record, and pick context for selected teams.
sleeper_transactions	Fetch trades, waivers, and free-agent moves by week range.
sleeper_matchups	Fetch one week's matchups, starters, bench, and points.
sleeper_draft_board	Fetch draft settings, order, picks, and traded slots.
sleeper_search_players	Resolve player names to Sleeper player records.
sleeper_trending_players	Fetch frequently added or dropped players.

Configuration

Environment variable	Required	Description
SLEEPER_USERNAME	Yes, unless using SLEEPER_USER_ID	Sleeper username used to locate the account.
SLEEPER_USER_ID	Optional	Stable user ID; takes precedence over the username.
SLEEPER_DEFAULT_SEASON	Optional	Four-digit season used when a tool does not provide one.
SLEEPER_CACHE_DIR	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.json

Delete 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 check

The 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_USERNAME

Start the STDIO server manually:

SLEEPER_USERNAME=YOUR_SLEEPER_USERNAME npm start

The 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.md

Troubleshooting

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 node

Use 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.json

The 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.