Skip to main content
Glama
fantasy-mcp

fantasy-mcp

by jolfr

fantasy-mcp

Gives Claude read-only access to your ESPN fantasy football team: your roster, this week's matchup, free agents, and player profiles.

Install in Claude Desktop

  1. Download fantasy-mcp.mcpb (under Assets) from the latest release.

  2. Double-click the file (or in Claude Desktop: Settings → Extensions → Advanced settings → Install Extension… and pick it).

  3. Claude Desktop will warn that the extension isn't signed by Anthropic — that's expected for this project; choose Install.

  4. Skip the settings form (leave it empty and click Save) — you'll do setup in chat.

  5. Start a new chat and say set up my fantasy league. A card walks you through copying two cookies from your browser and your league ID, then tests the connection.

  6. Ask "how's my fantasy team doing?"

The first launch takes a minute while Claude Desktop downloads Python and the server's dependencies. Nothing else needs to be installed.

Related MCP server: Sleeper Fantasy Football MCP Server

Get your ESPN cookies and league ID

ESPN has no public API, so the server signs in with the same two cookies your browser uses. They are private — do not share them.

Chrome (or Edge, Brave)

  1. Go to fantasy.espn.com and make sure you're logged in.

  2. Open DevTools: right-click anywhere on the page and choose Inspect, or press Cmd+Option+I (Mac) / F12 or Ctrl+Shift+I (Windows).

  3. Click the Application tab. In the left sidebar, under Storage, expand Cookies and click https://fantasy.espn.com.

  4. Find the rows named espn_s2 and SWID. Click a row, then copy its Value from the box below the table. Leave Show URL-decoded unchecked — the decoded value won't work. Paste each into the matching box in the setup card (or the settings form), keeping the curly braces on SWID.

Safari (Mac)

  1. Enable the Develop menu once: Safari → Settings → Advanced → Show features for web developers.

  2. Go to fantasy.espn.com, logged in.

  3. Develop → Show Web Inspector, then the Storage tab → Cookies → fantasy.espn.com.

  4. Click the espn_s2 row and copy its Value; then do the same for SWID.

League ID

Open your league on fantasy.espn.com. The number after leagueId= in the address bar is your League ID.

Prefer not to type cookies in chat?

Enter them in Settings → Extensions → ESPN Fantasy Football instead; Claude Desktop keeps them in your keychain. Values saved from the chat card take precedence over the settings form.

When cookies expire

ESPN cookies expire every few weeks. When they do, tools fail with a message mentioning "cookies". Say update my ESPN cookies and fill in the card again (or update the settings form if you used that).

Optional settings

  • Season (optional) — defaults to the current calendar year. Set it explicitly from January to July if you want to keep looking at last season.

  • Team ID (optional) — normally auto-detected from your SWID. Set it only if the server reports it can't find your team; it's the teamId= number in your team's URL.

Use with Claude Code or other MCP clients

Install uv (Python 3.12+), then:

git clone https://github.com/jolfr/fantasy-football-mcp fantasy-mcp
cd fantasy-mcp
cp .env.example .env   # fill in the same values as above
uv sync

.mcp.json in this repo registers the server automatically when you run claude here. For other projects or clients, add:

{"mcpServers": {"fantasy": {"command": "uv",
  "args": ["run", "--directory", "/path/to/fantasy-mcp", "fantasy-mcp"]}}}

If you also use Claude Desktop, values saved from the in-chat setup card (~/Library/Application Support/fantasy-mcp/config.json on macOS, ~/.config/fantasy-mcp/config.json on Linux, %LOCALAPPDATA%\fantasy-mcp\config.json on Windows) take precedence over .env.

Tools

  • whoami — confirms auth; returns league name, season, your team.

  • setup — shows the in-chat setup card; save_settings stores and verifies what you enter.

  • get_league_settings — scoring rules (with a one-line summary), lineup slots, position limits, playoff format, waiver and trade rules.

  • get_standings — every team's rank, record, points, streak, ESPN projected finish, waiver priority, transaction counts, and playoff clinch status.

  • get_my_team — your record, points, and roster with lineup slots.

  • get_team — any other team's roster by id, name, or abbreviation, with owner and current-week projections (trade targets, positional depth).

  • get_matchup — head-to-head for the current week (or any week): live score, projection, win probability, and both rosters with per-player actual/projected points.

  • get_projections — this (or any) week's ESPN projections for your roster with opponent/bye/kickoff, plus a suggested optimal lineup and the start/sit changes to reach it.

  • get_free_agents — available players (free agents + waivers), optionally by position, sorted by % rostered or season projection, with ownership trend, projections, and positional rank.

  • get_transactions — league transaction log (adds, drops, trades, waiver claims including pending ones), newest first, optionally filtered to one team, with a one-line summary per transaction.

  • get_player — one player's full profile by name or id: league ownership, season totals/projection, ESPN outlook, and a per-week game log with stat lines for this season and last. In clients that support MCP Apps (Claude Desktop, claude.ai) this renders as an interactive card; elsewhere the JSON profile is returned as text.

  • compare_players — 2–6 players side by side: this week's projection and opponent, season pace, recent form, last season, league availability, ownership trend.

Nothing here can change your team; it is read-only.

Develop

uv sync
uv run pytest

Build a local extension bundle to test in Claude Desktop:

npx -y @anthropic-ai/mcpb@2.1.2 pack . fantasy-mcp.mcpb

Release

  1. Bump version in both pyproject.toml and manifest.json (they must match — tests/test_manifest.py checks this).

  2. Commit, then git tag vX.Y.Z && git push origin main --tags.

  3. The Release workflow tests, packs, and attaches fantasy-mcp.mcpb to a GitHub Release for the tag.

Available Tools

13 tools
compare_playersCompare PlayersA

Compare 2-6 players side by side for "X or Y?" decisions.

players may mix names and player_ids (ids from other tools are precise; names are matched against ESPN's active-player index). Ambiguous or unknown names are returned in unresolved with candidate ids -- retry just those, the rest still come back. week defaults to the league's current NFL week; pass next week's number to plan ahead.

Each row: identity/status/owned_by; week {projected, opponent, kickoff}; season {projected, points, positional_rank, games, avg}; last_3 (points in the most recent games this season, newest first); last_season {points, games, avg} or null; percent_owned / percent_change (ESPN-wide ownership and trend). Rows keep the input order.

Inputs: players (required), week. Returns: object

get_free_agentsGet Free AgentsA

List available players (free agents and waiver claims) in the user's league.

Use this for "who should I pick up?", "best available RB", or "who's trending".

Args: position -- one of QB, RB, WR, TE, K, D_ST (case-insensitive; D/ST also accepted); omit for all positions. limit -- 1 to 50, default 10. sort -- "owned" (most rostered across ESPN first, default) or "projected" (highest season projection first).

Each player row: player_id (pass to get_player), name, position, pro_team, injury_status, status (FREEAGENT = add immediately; WAIVERS = must submit a claim), percent_owned (% of ESPN leagues rostering them), percent_change (ownership trend -- positive means being picked up), season_projected / season_points (full-season projected / scored so far), week_projected / week_points (current NFL week; 0.0 may mean not played yet OR played and scored nothing), and positional_rank (ESPN's season rank at their position; null if unavailable). Next-week projections are not available from this tool.

Inputs: sort, limit, position. Returns: object

get_league_settingsGet League SettingsA

League rules: scoring, roster construction, schedule/playoffs, waivers, trades.

Call this before start/sit, pickup, or trade advice so recommendations use this league's scoring (scoring.ppr = points per reception; scoring.summary is a one-line description; scoring.rules maps stat names -- the same names get_player's game log uses -- to points, with unmapped ESPN ids as stat_). roster.lineup gives starting slots and bench/IR counts; roster.position_limits caps how many of a position a team may roster. waivers describes the claim system (budget is FAAB dollars when present); trades.deadline is a UTC date.

Inputs: no named parameters. Returns: object

get_matchupGet MatchupA

Return the user's head-to-head matchup for the current week (or a given week).

Use this for "am I winning?", "who am I playing?", or "should I have started X?". week defaults to the current matchup period (current_week); pass an earlier week for a final result or next week's number for a preview with projections. There is no per-player game-state field: points of 0.0 may mean the player has not played yet OR played and scored nothing -- do not claim to know which.

Top level: week; status (UPCOMING, IN_PROGRESS, or FINAL); is_home; my_team; opponent. Each team has: team_id, name, abbrev, score (fantasy points so far this week), projected (ESPN's live projection for the week's final score, or for a future week the sum of starters' player projections -- see projected_source: "espn" | "sum_of_starters" | null), win_probability (0-1, may be null), and roster. Each roster row has the same fields as get_my_team (player_id, name, position, slot, pro_team, injury_status) plus points (scored so far this week) and projected (ESPN's projection for this player this week; null if unavailable). Only rows whose slot is not BENCH or IR count toward score.

Inputs: week. Returns: object

get_my_teamGet My TeamA

Return the user's fantasy team: season record, points, and full roster.

Each roster row has: player_id (pass to get_player); name; position (the player's NFL position, e.g. QB/RB/WR); slot (the fantasy lineup slot — BENCH and IR mean not starting, anything else is a starter); pro_team (NFL team abbreviation); injury_status; projected (ESPN's projection for the current NFL week, null if unavailable). Rows are ordered starters first, then bench, then IR. Record and points are season-to-date for the configured season.

Inputs: no named parameters. Returns: object

get_playerGet PlayerA

Full profile for one player: status, league ownership, season numbers, outlook, game log.

Use this for "tell me about X", "how has X been doing", "who has X in my league", or "is X worth a claim". Pass exactly one of: name (full name is best; a partial name works if it matches one active player) or player_id (from any other tool's rows -- prefer this when you have it).

Returns: player_id, name, position, pro_team, injury_status, injured, eligible_slots; league_status (ONTEAM / FREEAGENT / WAIVERS) and owned_by (the league team rostering them, or null); ownership across all ESPN leagues (percent_owned, percent_started, percent_change = trend, adp); season {year, projected, points, positional_rank}; last_season {year, points}; outlook (ESPN's written preseason summary); game_log newest first, each week with points, projected (null until ESPN publishes it), and stats -- raw counts such as rush_yds, targets, pass_td, fg_made_40_49, dst_sacks (zero-valued stats omitted). Covers this season and last. No news articles or opponent-matchup ratings. Name lookup uses a snapshot of ESPN's active-player list taken when the server started; a player signed since then may not resolve by name but still works by player_id. In clients that support MCP Apps this renders as a card; the JSON profile is always returned as text. headshot_url points at ESPN's CDN (team logo for a D/ST) and is not verified to exist.

Inputs: name, player_id.

get_projectionsGet ProjectionsA

ESPN projections for the user's roster for one NFL week, with a suggested optimal lineup.

Use this for "set my lineup", "start X or Y?", or "who's on bye?". week defaults to current_week (the league's current NFL week, which ESPN keeps until the week's games finish); to plan ahead once games have kicked off, call again with week = current_week + 1. Projections are null until ESPN publishes them.

players: every rostered player with slot (current lineup slot), opponent ("@KC" away, "vs KC" home, "BYE"), kickoff (UTC), and projected (ESPN's points projection for that week; null if ESPN has none). suggested_lineup fills this league's starting slots (including FLEX/superflex slots and their eligibility rules) to maximize projected points; players on IR or marked OUT/suspended are never started. changes lists who to start (with their suggested slot) and who to sit (with their current slot) to get there, plus the projected gain; a continuing starter that merely moves slots appears only in suggested_lineup. Present changes to the user rather than the whole table when they ask for lineup advice.

Inputs: week. Returns: object

get_standingsGet StandingsA

League standings: rank, record, points for/against, streak, projected finish, waiver order.

Use this for "where do I stand", "who's in the playoff picture", "who has the top waiver priority", or "who's been active on waivers/trades". Teams are ordered by ESPN's playoff seed (falling back to wins then points for when ESPN hasn't seeded yet, e.g. preseason); is_me marks the user's team; owner is the ESPN member name; projected_rank is ESPN's projected final standing; clinched is set once a team has clinched a playoff spot. Records and points update when ESPN finalizes each week (use get_matchup for live scores).

Inputs: no named parameters. Returns: object

get_teamGet TeamA

Another league team's roster: record, points, and players with current-week projections.

Use this for trade targets, "who has the most RBs", or "what does Lucas's team look like". team is a team id (from get_standings or get_matchup) or a name / abbreviation (case-insensitive; a partial name works if unique). Same shape as get_my_team: owner, record, points_for/against, and roster rows with player_id, name, position, slot, pro_team, injury_status, and projected for the current NFL week.

Inputs: team (required). Returns: object

get_transactionsGet TransactionsA

League transaction log: adds, drops, waiver claims (including pending), and trades.

Use this for "who dropped X", "did my waiver claim go through", recent trades, or waiver activity. Newest first. A pending waiver claim has status PENDING; its processed field is when ESPN will run it (already executed claims/trades have processed set to when they ran). Lineup moves (bench/slot changes, not adds or drops) are hidden unless include_lineup_moves is true -- they rarely matter for these questions.

Args: team -- id or name/abbreviation (case-insensitive, partial name ok) to filter to one team's transactions, including trades where that team is the other side; omit for the whole league. limit -- 1 to 100, default 25.

Each row: id, type (WAIVER, FREEAGENT, TRADE, LINEUP, or DRAFT), status (e.g. PENDING, EXECUTED, DECLINED, VETOED), espn_type (ESPN's raw type, e.g. TRADE_ACCEPT), week, team (who initiated it), proposed/processed (UTC timestamps), bid (FAAB dollars, 0 if none), items (action ADD/DROP/ LINEUP/TRADE/DRAFT, player_id, name -- null if not in the player index -- position, pro_team, from_team/to_team, from_slot/to_slot), and a one-line summary.

Inputs: team, limit, include_lineup_moves. Returns: object

save_settingsSave SettingsA

Save ESPN credentials and league id, then verify them against ESPN.

Normally called by the setup card's Save & test button; you may call it directly if the user pasted values into the chat. Returns {"ok": true, "league_name", "team_name", "season"} on success, or {"ok": false, "error": "..."} with a message to relay. Values are stored in a per-user config file that takes precedence over the extension's settings form. Values are written to the config file before the ESPN check, so on an ok: false cookie error they are already saved (tell the user to re-copy espn_s2/SWID); on a validation error nothing is written.

Inputs: swid, espn_s2, league_id. Returns: object

setupSetupA

Show the in-chat setup card for connecting the user's ESPN league.

Call this when any tool reports the league is not configured, or when the user asks to set up, connect, update, or change their league or cookies. The card explains where to find the espn_s2 and SWID cookies, has one input per value, and saves + verifies them via save_settings. Ask the user to fill in the card; do not ask them to paste cookies into the chat. If this client cannot display cards, tell the user to set the values in the extension's settings in Claude Desktop or in .env for a local checkout (see README).

Inputs: no named parameters.

whoamiWhoamiA

Verify ESPN credentials and league configuration.

Call this first. Cheap (one small request, no roster data). Returns the league id/name, season, and the user's team id/name. Fails with an explanatory message if cookies are expired or the league/team can't be resolved.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: credential checks, settings, roster views, player profiles, standings, matchups, projections, transactions, and comparisons. Even similar tools like get_my_team and get_team differ by target team, and get_player vs compare_players are clearly separated by context.

    Naming Consistency5/5

    Names follow a consistent verb_noun pattern with get_* for retrieval operations and descriptive verbs for others (save_settings, setup, compare_players). No mixed conventions or ambiguous verbs.

    Tool Count5/5

    13 tools is well within the ideal range for a domain-specific server. Each tool covers a necessary aspect of fantasy football information retrieval without redundancy or bloat.

    Completeness5/5

    The surface covers all major fantasy football queries: team rosters, standings, matchups, player details, free agents, transactions, projections, and lineup advice. League settings and credential management are included, making the tool set self-sufficient for read-only use.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects Claude to Sleeper fantasy football leagues, providing read-only tools for rosters, matchups, standings, transactions, player search, and trending players, with multi-league support.
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Gives Claude Desktop read access to an ESPN Fantasy Football league, exposing standings, rosters, matchups, free agents, trades, and schedules so users can ask about their league in natural language. Adds purpose-built tools for trade targeting, roster-improvement analysis, and projection-based start/sit advice.
      20
      -