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., "@fantasy-mcp how's my fantasy team doing?"
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.
Gives Claude read-only access to your ESPN fantasy football team: your roster, this week's matchup, free agents, and player profiles.
Download fantasy-mcp.mcpb (under Assets) from the
latest release.
Double-click the file (or in Claude Desktop: Settings → Extensions → Advanced settings → Install Extension… and pick it).
Claude Desktop will warn that the extension isn't signed by Anthropic — that's expected for this project; choose Install.
Fill in the form: espn_s2 cookie, SWID cookie, and League ID. See Get your ESPN cookies and league ID below. Leave Season (optional) and Team ID (optional) blank unless you need them.
Start a new chat and 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: Yahoo Fantasy Baseball MCP
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.
Go to fantasy.espn.com and make sure you're logged in.
Open DevTools: right-click anywhere on the page and choose Inspect,
or press Cmd+Option+I (Mac) / F12 or Ctrl+Shift+I (Windows).
Click the Application tab. In the left sidebar, under Storage,
expand Cookies and click https://fantasy.espn.com.
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
field in Claude Desktop, keeping the curly braces on SWID.
Enable the Develop menu once: Safari → Settings → Advanced → Show features for web developers.
Go to fantasy.espn.com, logged in.
Develop → Show Web Inspector, then the Storage tab → Cookies
→ fantasy.espn.com.
Click the espn_s2 row and copy its Value; then do the same for
SWID.
Open your league on fantasy.espn.com. The number after leagueId= in the
address bar is your League ID.
ESPN cookies expire every few weeks. When they do, tools fail with a message mentioning "cookies". Copy fresh values from your browser into Settings → Extensions → ESPN Fantasy Football in Claude Desktop.
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.
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"]}}}whoami — confirms auth; returns league name, season, your team.
get_league_settings — scoring rules (with a one-line summary), lineup slots, position limits, playoff format, waiver and trade rules.
get_my_team — your record, points, and roster with lineup slots.
get_matchup — this week's head-to-head: live score, projection, win
probability, and both rosters with per-player actual/projected points.
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_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.
Nothing here can change your team; it is read-only.
uv sync
uv run pytestBuild a local extension bundle to test in Claude Desktop:
npx -y @anthropic-ai/mcpb@2.1.2 pack . fantasy-mcp.mcpbBump version in both pyproject.toml and manifest.json (they must
match — tests/test_manifest.py checks this).
Commit, then git tag vX.Y.Z && git push origin main --tags.
The Release workflow tests, packs, and attaches fantasy-mcp.mcpb to a
GitHub Release for the tag.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | owned | |
| limit | No | ||
| position | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it explains status values (FREEAGENT vs WAIVERS), ownership trend interpretation, the ambiguity of 0.0 week points, and explicitly notes next-week projections are unavailable. This goes well beyond a basic list description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: purpose and usage are front-loaded, args are compact, and the row-field explanation adds semantic nuance. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-optional-parameter list tool with no annotations, the description covers what the tool does, when to use it, all parameter semantics, and the meaning of every returned field. Nothing needed to invoke or interpret results is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully documents all three parameters: position values including aliases and case-insensitivity, limit range and default, and sort options with their meanings. It compensates completely for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List available players (free agents and waiver claims) in the user's league', a specific verb and resource that clearly distinguishes it from sibling tools like get_my_team or get_player. The scope ('available', 'free agents and waiver claims') makes its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases: 'who should I pick up?', 'best available RB', or 'who's trending'. It does not explicitly state when to prefer a sibling tool, though the output row directs passing player_id to get_player, providing a mild routing hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It goes beyond a simple 'returns settings' by explaining important value semantics: scoring.rules maps stat names to points, unmapped ESPN ids appear as stat_<id>, FAAB budget is present when applicable, and trades.deadline is a UTC date. It does not discuss read-only status or data freshness, but the tool name and lack of parameters make those less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a compact summary of the returned categories, then uses each subsequent sentence to add meaningful detail about how to interpret the fields. It is dense but every sentence earns its place, with no filler or repetition of schema data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter settings retrieval tool, this is complete: it explains the major output sections, clarifies edge cases in scoring and trade data, and tells the agent when to call it. The presence of an output schema reduces the need to re-describe raw return shapes, and the description adds the interpretive context the schema likely cannot.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter meanings to clarify beyond the schema. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on output shape and interpretation rather than inventing parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (league settings) and enumerates its contents: scoring, roster construction, schedule/playoffs, waivers, and trades. It is immediately distinguishable from siblings like whoami, get_my_team, and get_free_agents because it is the only tool focused on league-wide rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use directive: 'Call this before start/sit, pickup, or trade advice.' It references get_player for stat-name conventions, but does not explicitly state when not to use this tool or name alternatives for other tasks, so it stops short of the full when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the user's current-week head-to-head matchup with live scoring.
Use this for "am I winning?", "who am I playing?", or "should I have started X?". Covers the current week only. 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), 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, and it excels. It discloses that points of 0.0 are ambiguous (player may not have played or scored nothing), explicitly says not to claim which, explains the status field values, and clarifies that only non-BENCH/IR slots count toward score. It also describes the full response structure including win_probability nullability. No contradictions with annotations (none present).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but each sentence adds meaningful information. It leads with the primary purpose and usage examples, then provides the response structure and caveats. It is well-organized and front-loaded, though slightly verbose in the roster field enumeration; still efficient for the complexity it covers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are no parameters and an output schema exists (though not shown), the description fully explains what the agent will receive: top-level fields, team fields, roster fields, and scoring rules. It also addresses the key edge case (0.0 points) and the projection nullability. Nothing an agent needs to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the description has no parameter semantics to add. Per the rubric, 0 parameters gives a baseline of 4. The description correctly does not fabricate parameter details, and the schema is empty with 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what the tool does: returns the current-week head-to-head matchup with live scoring. The verb 'Return' plus the specific resource ('user's current-week head-to-head matchup') is unambiguous. It also distinguishes itself by limiting to the current week, which is not covered by sibling tools like get_my_team or get_free_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: 'Use this for "am I winning?", "who am I playing?", or "should I have started X?"' and adds a scope limitation ('Covers the current week only'). This gives the agent clear criteria for when to invoke this tool versus alternatives, even though it does not name siblings directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Rows are ordered starters first, then bench, then IR. Record and points are season-to-date for the configured season.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides meaningful behavioral detail beyond the basic 'return' action: roster row schema, slot semantics for starters vs BENCH/IR, ordering, and season-to-date scope. It does not mention edge cases like an empty team or auth requirements, but for a read-only retrieval this is strong transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The summary sentence is front-loaded, and the remaining sentences pack in every useful detail about the output without repetition or filler. Every sentence earns its place by providing information an agent needs to interpret the response.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument tool, the description is contextually complete: it fully documents the return payload, roster field semantics, row ordering, and season scope. An agent can correctly select the tool and interpret the result without needing to open any sibling tool schemas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and schema description coverage is 100%, so there is no parameter ambiguity for the description to resolve. The baseline of 4 applies because the description correctly focuses on output rather than inventing parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Return the user's fantasy team') and enumerates the contents (record, points, roster). It distinguishes itself from sibling tools like get_matchup and get_free_agents, and even references get_player as a follow-up, making the tool's scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as the tool for the current user's own team with season-to-date stats, making its use case apparent from context. It does not explicitly state exclusions or name alternative conditions, but no explicit exclusions are needed given the zero-parameter scope and distinct sibling purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| player_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does so thoroughly. It discloses the name lookup snapshot limitation, game log ordering, zero-valued stat omission, headshot_url verification caveat, season coverage, and rendering behavior. This is far beyond what annotations could provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries operational value: usage conditions, parameter semantics, full return structure, caveats, and rendering notes. It is front-loaded with the core purpose and usage before diving into field details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, zero annotations, and no output schema, the description is remarkably complete. It covers inputs, output fields, data provenance, limitations, and return format, leaving an agent with enough information to invoke the tool correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates by explaining both parameters: name semantics ('full name is best; a partial name works if it matches one active player') and player_id semantics ('from any other tool's rows -- prefer this when you have it'). It also clarifies the relationship between them with 'Pass exactly one of'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Full profile for one player' with a detailed list of contents including status, league ownership, season numbers, outlook, and game log. It clearly distinguishes this from siblings like get_free_agents and get_my_team by focusing on a single player's profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('tell me about X', 'how has X been doing', 'who has X in my league', 'is X worth a claim') and parameter selection guidance. It also states exclusions ('No news articles or opponent-matchup ratings'), but does not explicitly name sibling tools as alternatives, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden and does so thoroughly. It discloses the request cost, that no roster data is fetched, exactly what fields are returned, and the failure mode with an explanatory message when cookies expire or the league/team cannot be resolved. This is model behavior for a zero-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, information-dense sentences with no filler. It front-loads the core purpose and 'Call this first' instruction, then supplies cost, return details, and failure behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter preflight tool with an output schema present, the description is complete: it covers when to call it, what it returns, cost characteristics, failure modes, and error messaging. There is no significant information an agent needs that is missing. The output schema handles return-value detail, so the description's summary of return fields is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema trivially covers this with an empty properties object. Per the baseline for zero-parameter tools, the description need not add parameter semantics. It adds value by describing what is returned rather than parameters, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Verify ESPN credentials and league configuration', and the phrase 'Call this first' immediately positions it as a preflight/bootstrap check. It distinguishes itself from sibling data-fetching tools by noting it returns the league and team identifiers, not league settings, matchup, or free-agent data. This is enough for an agent to know what the tool is for and how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this first' and supports that with cost and scope information: 'Cheap (one small request, no roster data)'. This gives concrete guidance on when to invoke it before more expensive or data-heavy sibling calls. It also indicates when not to expect detailed data, effectively distinguishing it from retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0get_free_agentsget_league_settingsget_matchupget_my_teamget_playerwhoamiScored across 6 tools
Each tool has a clearly distinct purpose: identity/config, league rules, own roster, weekly matchup, free-agent pool, and player profile. Even get_my_team and get_matchup both return roster rows, their contexts are distinct and cross-references via player_id make selection unambiguous.
Five of six tools follow a consistent get_<noun> snake_case pattern, which is predictable and clear. whoami is the lone outlier, though it is a conventional identity command and the deviation is minor.
Six tools is a tightly scoped, well-sized surface for a fantasy football assistant. Each tool earns its place and there is no redundancy or bloat.
The read-only fantasy football workflow is well covered: identity, scoring/rules, roster, matchup, waivers, and player research. Notable gaps include no league standings/overview tool and no transaction endpoints, but the descriptions consistently frame this as an advice/analysis server, so these are minor rather than fatal.
Read-only ESPN, Sleeper, and Fantrax fantasy leagues for Claude, ChatGPT, and other AI tools.
Read-only fantasy analysis for ESPN, Yahoo, and Sleeper leagues via MCP
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
