espn-fantasy-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., "@espn-fantasy-mcp add the best available quarterback from waivers"
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.
espn-fantasy-mcp
A local MCP server that reads and writes ESPN fantasy sports (football, basketball, baseball) using your own ESPN session cookies. It replaces manually driving a browser pane for ESPN: Claude Code or Codex can call its tools directly. No web UI, no cloud, no server — one Node process talking stdio to your AI client, and HTTPS to ESPN.
It does not propose, accept, or reject trades. That's out of scope permanently.
Setup (do this once)
These steps are written to be followed exactly, in order — copy-paste the commands.
1. Prerequisites
Node.js 20 or newer (
node --version)An ESPN account that's a member of the fantasy league you want to control
Git and (optionally) the GitHub CLI (
gh) if you're cloning from a private repo
2. Clone and install
git clone <this-repo-url> espn-fantasy-mcp
cd espn-fantasy-mcp
npm install
npm run buildnpm run build compiles src/ to dist/index.js, which is what your MCP client will actually launch.
3. Get your ESPN cookies
ESPN's fantasy API isn't public — it authenticates the same way your browser does, with two cookies. There is no username/password step; you copy these two values once and they last about a month.
Log into
https://fantasy.espn.comin any browser, and open your league.Open DevTools (F12 or right-click → Inspect).
Go to Application (Chrome/Edge) or Storage (Firefox) → Cookies →
https://fantasy.espn.com.Find the cookie named
espn_s2— copy its whole value (it's long).Find the cookie named
SWID— copy its value including the curly braces, e.g.{ABCDEF12-3456-7890-ABCD-EF1234567890}.
Never paste these into a chat with an AI assistant, an issue, or a commit. They go in one place only: your local .env file, which is already listed in .gitignore.
4. Configure
cp .env.example .envEdit .env:
ESPN_S2=<paste the espn_s2 value>
ESPN_SWID=<paste the SWID value, with braces>
ESPN_SPORT=ffl # ffl = football, fba = basketball, flb = baseball
ESPN_SEASON=2026
ESPN_LEAGUE_ID=<your league id — the number in your league's ESPN URL>
ESPN_TEAM_ID=<your team id in that league>
WRITES_ENABLED=false # leave false until you've checked dry runs look rightYour league id and team id are both visible in the URL when you're looking at your team on fantasy.espn.com (...leagueId=XXXXXXX...&teamId=N).
5. Sanity-check it runs
node dist/index.jsYou should see espn-fantasy-mcp running (sport=..., season=..., writes disabled (dry run only)) printed to stderr, and the process will sit waiting for stdio input — that's correct for an MCP server. Ctrl+C to stop it. If you see an error about ESPN_S2 and ESPN_SWID are not set, go back to step 4.
Related MCP server: sleeper-mcp
Connect it to your AI client
Claude Code
claude mcp add espn-fantasy -- node /absolute/path/to/espn-fantasy-mcp/dist/index.js --scope user--scope user makes it available in every Claude Code session on this machine, not just the current project. Alternatively, drop this in a project's .mcp.json:
{
"mcpServers": {
"espn-fantasy": {
"command": "node",
"args": ["/absolute/path/to/espn-fantasy-mcp/dist/index.js"]
}
}
}Codex
Add to Codex's MCP server config (~/.codex/config.toml or equivalent):
[mcp_servers.espn-fantasy]
command = "node"
args = ["/absolute/path/to/espn-fantasy-mcp/dist/index.js"]Restart Claude Code / Codex after adding the server.
Tools
Every tool takes sport, season, league_id (all default from .env if omitted). Write tools also take team_id.
Reads (no confirmation needed, rate-limited to 2/sec, not logged)
Tool | What it does |
| Settings: scoring, roster slots, acquisition/waiver settings, schedule, trade settings, current scoring period |
| Team ids, names, owners, records, waiver rank |
| Every team's roster (or one |
| Free agents / waiver wire, filterable by slot, sorted by ownership or projection |
| A scoring period's matchups: totals and live projections |
| A scoring period's per-player actuals |
| Executed transactions (adds, drops, trades, draft picks), most recent first, resolved to player names. Paginated ( |
| Pending waiver claims and trade proposals (read-only — this server never acts on trades) |
| Look up a player by id or name search |
| League state in the line-oriented text format used by |
| Suggests a starting lineup (fills the most restrictive slots first, then best remaining projection), ranked by season or a specific scoring period. A heuristic suggestion only — apply it yourself via |
Writes (rate-limited to 1 per 5 sec, every real send logged to logs/writes.jsonl)
Every write tool takes dry_run (default true). A dry run validates and reports what would be sent without sending it. Setting dry_run: false only actually executes if WRITES_ENABLED=true in .env — otherwise it's still treated as a dry run. After a real write, the tool re-reads the affected state and returns it so you can confirm the change landed.
Tool | What it does |
| Apply a batch of |
| Add an unclaimed free agent, optionally dropping another player |
| Submit a waiver claim, optional conditional drop, optional FAAB |
| Cancel a pending waiver claim by transaction id |
| Move a player to IR/IL (a lineup move to the IR slot) |
| Move a player out of IR/IL into an active or bench slot |
Not implemented, ever: proposing, accepting, or rejecting trades.
Known limits — read before relying on this
This uses an undocumented API. ESPN can change response shapes or payloads at any time without notice; nothing here is officially supported.
Cookies expire, typically after about a month. When a request that used to work starts returning a clear "refresh your cookies" error, go back to step 3 above. The server never retries a 401 and never prints cookie values, even in error messages or logs.
set_lineup(and themove_to_ir/activate_from_irtools built on it) can execute real writes — the lineup-move payload was captured live on 2026-09-10 (see The lineup-move payload below) and is implemented inbuildLineupBodyinsrc/espn/writes.ts, verified in dry run against a real roster.Rate limits are conservative and process-local (2 reads/sec, 1 write per 5 sec) — fine for one interactive AI client, not built for concurrent callers.
The read/write endpoint split matters: reads go to
lm-api-reads.fantasy.espn.com, writes tolm-api-writes.fantasy.espn.com. Mixing them up produces confusing errors.
The lineup-move payload
Captured live on 2026-09-10 from a real bench↔FLEX swap. ESPN's lineup UI sends the move as a ROSTER transaction with one LINEUP item per player whose slot changed — a two-way swap is two items, each carrying that player's own prior slot as fromLineupSlotId:
{
"isLeagueManager": false, "teamId": 5, "type": "ROSTER",
"memberId": "{SWID}", "scoringPeriodId": 1, "executionType": "EXECUTE",
"items": [
{"playerId": 4429023, "type": "LINEUP", "fromLineupSlotId": 20, "toLineupSlotId": 23},
{"playerId": 4568490, "type": "LINEUP", "fromLineupSlotId": 23, "toLineupSlotId": 20}
]
}Implemented in buildLineupBody in src/espn/writes.ts. If ESPN ever changes this shape, re-capture it the same way:
Open a fantasy.espn.com team page in a logged-in browser, on your team's roster tab.
Open DevTools Console and paste an interceptor, then press Enter. Note: ESPN's lineup-move request is sent via
XMLHttpRequest, notfetch— afetch-only interceptor (like the one used for the waiver-claim/cancel-claim payloads) will silently miss it. Wrap both:(function(){ const of = window.fetch; window.fetch = async function(u,o){ try{ if(String(u).includes('lm-api-writes')){ const a=JSON.parse(sessionStorage.ffcap||'[]'); a.push({kind:'fetch',u:String(u),m:o&&o.method,b:o&&o.body}); sessionStorage.ffcap=JSON.stringify(a);} }catch(e){} return of.apply(this,arguments); }; const open = XMLHttpRequest.prototype.open, send = XMLHttpRequest.prototype.send; XMLHttpRequest.prototype.open = function(method,url){ this.__cap_url=url; this.__cap_method=method; return open.apply(this,arguments); }; XMLHttpRequest.prototype.send = function(body){ try{ if(this.__cap_url && String(this.__cap_url).includes('lm-api-writes')){ const a=JSON.parse(sessionStorage.ffcap||'[]'); a.push({kind:'xhr',u:String(this.__cap_url),m:this.__cap_method,b:body}); sessionStorage.ffcap=JSON.stringify(a);} }catch(e){} return send.apply(this,arguments); }; })();Make one lineup move in the UI (drag a player, or use Move/Here) and confirm it.
Run
sessionStorage.ffcapin the console and copy the result.Redact
espn_s2andSWIDfrom anything captured before sharing or committing it.
Slot id reference
Football (ffl): 0 QB, 2 RB, 4 WR, 6 TE, 23 FLEX, 16 D/ST, 17 K, 20 Bench, 21 IR.
Basketball (fba): 0 PG, 1 SG, 2 SF, 3 PF, 4 C, 5 G, 6 F, 7 SG/SF, 8 G/F, 9 PF/C, 10 F/C, 11 UTIL, 12 Bench, 13 IR.
Baseball (flb): 0 C, 1 1B, 2 2B, 3 3B, 4 SS, 5 OF, 6 2B/SS, 7 1B/3B, 8 LF, 9 CF, 10 RF, 11 DH, 12 UTIL, 13 P, 14 SP, 15 RP, 16 Bench, 17 IL, 19 IF.
Full tables (including pro-team and stat-id maps) are in src/espn/constants.ts.
Development
npm run build # compile TypeScript
npm test # run unit tests (lineup validator, snapshot formatter)
npm start # run the compiled server directly
npm run dev # run from source with tsx, no build stepProject layout: src/index.ts (tool registration and output schemas), src/espn/client.ts (HTTP, cookies, rate limiting, 401 handling), src/espn/constants.ts (slot/team/position tables), src/espn/reads.ts / src/espn/writes.ts (API calls and payload building), src/lineup.ts (local lineup-move validation), src/optimalLineup.ts (the optimal_lineup suggestion algorithm), src/snapshot.ts (the text snapshot format), test/ (unit tests, no network).
Credits
The ESPN v3 fantasy API is undocumented; this project leans on prior reverse-engineering work rather than starting from scratch:
cwendt94/espn-api (Python) — the slot/position/pro-team/stat-id constant tables in
src/espn/constants.tsare ported from here, and thelineupLockedroster-entry field used for lock detection was confirmed from its player-parsing code.mkreiser/ESPN-Fantasy-Football-API (JavaScript) — read-endpoint client for cross-reference.
KBThree13/mcp_espn_ff — an existing Python MCP server for ESPN football reads, referenced for tool naming.
dylancharris's ESPN fantasy basketball MCP (LobeHub listing) — referenced for basketball tool coverage.stmorse's ESPN fantasy v3 API notes and the
ffscraprR package's endpoint vignette — view/endpoint documentation.tlo1216/frontoffice-manager'stools/scripts (snapshot-fetch.js,espn-cookie-fetch.mjs,diff-snapshot.mjs, and theespn-*-cheatsheet.mdfiles) — the source for the exact snapshot line format and the cheat-sheet facts this README andsrc/espn/constants.tsare cross-checked against.MCP TypeScript SDK —
@modelcontextprotocol/sdk, used directly.
License
MIT. See LICENSE.
Uses your own ESPN session. Not affiliated with, endorsed by, or supported by ESPN. ESPN's fantasy API is undocumented and unofficial, and automating it may be against ESPN's terms of service. You run this at your own risk.
Available Tools
17 toolsactivate_from_irActivate From IRA
Move one player out of the IR/IL slot into an active or bench slot, as a lineup move.
Inputs: to_slot (required), player_id (required), sport, season, +3 more. Returns: sent, dryRun, response, wouldSend, +3 more
add_free_agentAdd Free AgentA
Add an unclaimed free agent (not a waiver-wire player — use waiver_claim for those), optionally dropping another player in the same move.
Inputs: add_player_id (required), sport, season, dry_run, +3 more. Returns: sent, dryRun, response, wouldSend, +2 more
cancel_claimCancel ClaimADestructiveIdempotent
Cancel a pending waiver claim by its transaction id (from get_pending).
Inputs: transaction_id (required), sport, season, dry_run, +2 more. Returns: sent, dryRun, response, wouldSend, +2 more
get_boxscoreGet BoxscoreARead-onlyIdempotent
Per-player actual stats for a scoring period, for both teams in each matchup.
Inputs: scoring_period_id (required), sport, season, league_id. Returns: result
get_free_agentsGet Free AgentsARead-onlyIdempotent
Free agents and waiver-wire players, sorted by ownership percent (default) or projection. Optionally filter by lineup slot id (see get_league for slot ids, or the README's slot tables).
Inputs: limit, sport, season, sort_by, +2 more. Returns: result
get_leagueGet League SettingsARead-onlyIdempotent
League settings: scoring format, roster slot counts, acquisition (waiver) settings, schedule, trade settings, draft/keeper settings, and the current scoring/matchup period.
Inputs: sport, season, league_id. Returns: name, leagueId, seasonId, teamCount, +7 more
get_matchupsGet MatchupsARead-onlyIdempotent
Matchups for a scoring period: home/away team ids, live/final totals, and live projections.
Inputs: scoring_period_id (required), sport, season, league_id. Returns: result
get_pendingGet Pending TransactionsARead-onlyIdempotent
Pending waiver claims and trade proposals, with items resolved to player names. Trades are read-only here — this server never proposes, accepts, or rejects trades.
Inputs: sport, season, league_id. Returns: result
get_playerGet PlayerARead-onlyIdempotent
Look up one player by ESPN player id, or by a case-insensitive name substring search across rosters and free agents.
Inputs: id, sport, season, league_id, +1 more. Returns: id, name, locked, teamId, +11 more
get_rostersGet RostersARead-onlyIdempotent
Every team's roster, or one team's roster if team_id is given. Each player includes id, name, position, pro team, eligible slots, current lineup slot, injury status, lock state, and season/period projections.
Inputs: sport, season, team_id, league_id. Returns: result
get_teamsGet TeamsARead-onlyIdempotent
All teams in the league: id, name, owners, record, and waiver rank.
Inputs: sport, season, league_id. Returns: result
get_transactionsGet TransactionsARead-onlyIdempotent
Executed transactions (adds, drops, trades, lineup moves, draft picks), most recent first, with items resolved to player names. Paginated — a full season's draft alone can be 100+ records, so use limit/offset rather than expecting everything at once. Response includes total/count/offset/hasMore.
Inputs: limit, sport, offset, season, +1 more. Returns: count, total, offset, hasMore, +1 more
move_to_irMove to IRA
Move one player into the IR/IL slot, as a lineup move. Refuses if the player isn't eligible for IR or is locked.
Inputs: player_id (required), sport, season, dry_run, +2 more. Returns: sent, dryRun, response, wouldSend, +3 more
optimal_lineupOptimal Lineup SuggestionARead-onlyIdempotent
Suggests a starting lineup for one team: fills the most restrictive slots first (fewest eligible roster players), then the best remaining projection for each slot — the same approach the cheat sheets describe by hand. A heuristic, not a guaranteed-optimal assignment. Ranks by season projection by default, or by a specific scoring period's projection if scoring_period_id is given (a bye-week/no-game player ranks 0 for that period, not by season total). Locked players keep their current slot. This is a suggestion only — pass the resulting moves to set_lineup yourself if you want to apply them.
Inputs: sport, season, team_id, league_id, +1 more. Returns: bench, starters, usingPeriodProjection
set_lineupSet LineupA
Apply a batch of lineup moves to one team. Validates every move locally first (player is on the roster, target slot is eligible, player isn't locked, and the resulting lineup respects the league's slot counts) before sending anything. Rejected moves are reported with a reason and never sent.
Inputs: moves (required), sport, season, dry_run, +2 more. Returns: sent, dryRun, response, wouldSend, +3 more
snapshotLeague SnapshotARead-onlyIdempotent
The league in the exact line-oriented text format used by frontoffice-manager's tools/diff-snapshot.mjs: teamId|playerId|name|injury|seasonProj roster rows, FA|...|pctOwned free-agent rows, a SETTINGS line, a WAIVERORDER line, and a PEND: line, wrapped in SNAPSTART/SNAPEND markers.
Inputs: sport, season, league_id.
waiver_claimWaiver ClaimB
Submit a waiver claim, optionally with a conditional drop. bid is only used in FAAB leagues (see get_league's acquisitionSettings.acquisitionType); leave it unset in priority-waiver leagues.
Inputs: add_player_id (required), bid, sport, season, +4 more. Returns: sent, dryRun, response, wouldSend, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct resource or action: rosters vs. teams vs. player lookup, free-agent adds vs. waiver claims, and IR moves are clearly separated. The only near pair is add_free_agent vs. waiver_claim, but their descriptions explicitly distinguish unclaimed free agents from waiver-wire players.
Read operations consistently use get_* (get_teams, get_league, get_rosters, etc.), and mutations use action_noun patterns like set_lineup, add_free_agent, cancel_claim, and move_to_ir. Two outliers, snapshot and optimal_lineup, break the verb-first pattern, but they are still recognizable and not confusing.
Seventeen tools is slightly above the typical well-scoped range, but the count is justified by the variety of fantasy-football operations: league info, roster management, waivers, transactions, matchups, and IR handling. Each tool covers a meaningful need with little redundancy.
The surface covers the full roster-management lifecycle: viewing teams/rosters, adding/dropping players, submitting/canceling claims, setting lineups, and handling IR. The main gap is trade management, which is explicitly read-only via get_pending, so agents cannot propose or execute trades; otherwise the domain is well covered.
Maintenance
Related MCP Connectors
Fantasy football for any AI agent: draft board, start/sit, waivers, your Sleeper league. Free.
Free fantasy AI for ESPN, Sleeper, Fantrax: football, basketball and hockey in Claude and ChatGPT.
Fantasy analysis for your ESPN, Yahoo, and Sleeper leagues. Reads your leagues, never changes them.
ESPN MCP — keyless multi-sport live scores, teams, and news via ESPN's public site API.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceConnect ESPN & Yahoo fantasy leagues to AI assistants via MCP. Read-only tools for rosters, standings, matchups, free agents, and league info across football and baseball.23MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI models to manage and query fantasy sports leagues through the Sleeper API, supporting tasks like player lookups, league activity, and draft management.MIT
- AlicenseBqualityBmaintenanceEnables interaction with ESPN Fantasy Football leagues through natural language, allowing users to query rosters, matchups, and injuries, and execute actions via MCP or CLI.2MIT
- AlicenseBqualityBmaintenanceEnables reading Sleeper fantasy football rosters, matchups, standings, news, chat, and pick'em entries, with optional write actions for setting lineups, claiming waivers, and proposing trades.392MIT