fantasyFootballMCP

I lost last year's fantasy league, and I am determined to never lose again. Instead of studying draft tactics, doing deep dives on new players, obssesing over my lineup every week,,, I would rather create this :)

One of my mistakes last year was trusting ESPN analytics, so I used Claude to help me discover metrics and algos I can use to maximize my team's point potential per week.

I created an MCP server that answers the four questions a fantasy football manager actually asks (who should I start, should I make this trade, who should I pick up, will I make the playoffs) by doing the analysis in Python and returning the conclusion, not the data.

Let's jump in

$ optimize_lineup()
{
  "week": 8,
  "current_projected": 95.3,
  "optimal_projected": 106.1,
  "point_gain": 10.8,
  "win_prob_delta": 0.8,
  "swaps": [
    { "bench": "Tariq Whitlock", "starter": "Marcus Moreau",     "slot": "WR",   "gain": 10.7, "reason": "+10.7 projected points" },
    { "bench": "Devin Obi",      "starter": "Elijah Villanueva", "slot": "FLEX", "gain":  3.5, "reason": "+3.5 projected points" },
    { "bench": "Soren Quintero", "starter": "Dominic Okafor",    "slot": "RB",   "gain": -3.4, "reason": "Soren Quintero is OUT" }
  ],
  "caveats": []
}

Three swaps, 159 tokens. The alternative, handing the model sixteen players, their projections, their injury designations and the league's slot eligibility rules, and asking it to solve an assignment problem in context, costs ~31,900 tokens and gets the answer wrong, because the correct answer is a maximum-weight bipartite matching and not a sort.

Every transcript in this README is real output from uv run poe demo, which runs the whole tool surface against a committed fixture league. None of it is written by hand.

Quickstart

No ESPN account, no credentials, no network beyond PyPI:

git clone https://github.com/jeremylachowicz/fantasyFootballMCP
cd fantasyFootballMCP
uv sync
uv run poe demo

Connect Claude Desktop by adding this to claude_desktop_config.json:

{
  "mcpServers": {
    "fantasy-football": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/fantasyFootballMCP", "ffmcp"],
      "env": { "FFMCP_MODE": "demo" }
    }
  }
}

Or Claude Code, from inside the repo:

claude mcp add fantasy-football --env FFMCP_MODE=demo -- uv run ffmcp

Drop FFMCP_MODE=demo, copy .env.example to .env, and set FFMCP_LEAGUE_ID from your league's URL. Private leagues also need FFMCP_ESPN_S2 and FFMCP_SWID, the two session cookies from a logged-in ESPN browser session (DevTools → Application → Cookies → fantasy.espn.com). Those cookies are as sensitive as your ESPN password, so .env is gitignored and every error message is redacted before it can reach a log or a model. FFMCP_TEAM_ID picks which roster is "mine". Leave it unset and the server asks once through MCP elicitation. For streamable HTTP instead of stdio, run uv run poe serve and point a client at http://localhost:8000/mcp.

Related MCP server: baseclaw

What it does

Ten tools, four resources, three prompts. All output below is verbatim from the demo league.

Plus four resources (ffmcp://league/settings, ffmcp://league/teams, ffmcp://glossary, ffmcp://team/{team_id}/roster) that carry stable reference data with long cache TTLs instead of being re-fetched as tool calls, and three prompts (weekly_checkin, trade_workshop, playoff_push) that chain several tools into one routine.

Who should I start?

get_my_team shows the lineup as ESPN has it set. Note the running back ruled out and the receiver on bye, both still in the lineup: it is Sunday morning and nobody has touched it.

Week 8 — Team Alpha (3-4-0)
SLOT  PLAYER           POS  TM  PROJ  ST
QB    L. Petrov        QB   LAC 22.6
RB    S. Quintero      RB   DAL 11.8  O
RB    I. Adeyemi       RB   IND 9.6
WR    T. Whitlock      WR   SEA       BYE
WR    D. Rios          WR   GB  15.9
TE    L. Santoro       TE   NO  13.0
FLEX  D. Obi           TE   DET 6.9
D/ST  WSH D/ST         D/ST WSH 6.7
K     T. Prescott      K    MIN 8.8
BE    Q. Hargrove      QB   IND 19.4
BE    T. Moreau        RB   KC  6.9
BE    D. Okafor        RB   TEN 8.4
BE    M. Moreau        WR   NYG 10.7
BE    E. Villanueva    WR   NE  10.4
BE    D. Holloway      WR   BAL 6.9
IR    L. Novak         RB   MIA 5.2   I

optimize_lineup is the response at the top of this README: +10.8 projected points, worth +0.8 points of win probability this week. analyze_matchup prices the week:

Week 8: Team Alpha 106.1 vs Team Charlie 118.6 — 39% win prob
Biggest edges:
  RB: Team Charlie +25.9
  K: Team Alpha +8.8
  WR: Team Alpha +4.8
Swing player: D. Duval (WR MIA, ±9.4 pts)

Should I make this trade?

find_trades enumerates 1-for-1, 2-for-1 and 1-for-2 packages across every other roster, keeps only the ones both sides gain from, and ranks them by what they do to my playoff odds:

Team Bravo: give Q. Hargrove / get B. Battaglia — me +4.2%odds, them +11.2pts — Strengthens RB by 8.0 started pts/wk.
Team Bravo: give L. Petrov / get L. Castellan, T. Obi — me +4.0%odds, them +0.7pts — Strengthens RB by 9.8 started pts/wk.
Team Bravo: give L. Petrov / get C. Castellan, E. Brennan — me +3.4%odds, them +6.3pts — Strengthens RB by 6.7 started pts/wk.
Team Bravo: give L. Petrov / get L. Castellan — me +3.4%odds, them +21.0pts — Strengthens RB by 9.8 started pts/wk.
Team Bravo: give Q. Hargrove / get C. Castellan — me +3.4%odds, them +20.3pts — Strengthens RB by 6.7 started pts/wk.

The first row is the whole thesis of the trade module in one line. Quentin Hargrove is a 19.4-point quarterback, on a roster that already starts a 22.6-point quarterback, in a league with one QB slot. He is worth zero to Team Alpha, because he never plays. He is worth 6.5 points a week to Team Bravo, who start a 12.9-point quarterback. What a player is worth is a property of the roster, not of the player, and that asymmetry is the only reason trades happen. marginal_value measures it as the change in a roster's optimal lineup from adding or removing him, which is exactly why the optimizer had to be both correct and fast.

evaluate_trade prices one named offer from both sides:

{
  "verdict": "accept",
  "my_value_delta": 46.9,
  "partner_value_delta": 20.3,
  "my_playoff_odds_delta": 3.4,
  "positional_impact": "Strengthens RB by 6.7 started pts/wk.",
  "risks": []
}

An offer only one side gains from is a fleece and will be declined by any manager who does the same arithmetic, so those are filtered out rather than ranked low. The filter is the feature.

Who should I pick up?

find_waiver_targets ranks free agents by marginal value to this roster, not by projection, and not by how many people are adding them, and always names the drop, because a pickup recommendation without one is not advice:

PLAYER           POS  TM  PROJ  VAL    DROP
D. Ivanov        RB   CIN 12.4  +4.0   T. Whitlock
C. Fairbanks     WR   KC  13.1  +2.7   T. Whitlock
ARI D/ST         D/ST ARI 8.8   +2.1   T. Whitlock
I. Battaglia     WR   CHI 10.6  +0.2   T. Whitlock

Caleb Fairbanks is the higher projection. Devin Ivanov is the better pickup, because this roster is thin at running back and deep at receiver.

Will I make the playoffs?

simulate_season runs a vectorized Monte Carlo over the remaining schedule:

2,000 sims, weeks 8-14:
TEAM             REC     MEANW  PLAYOFF%  TITLE%
T. Echo          6-1     10.3   95.8%     27.8%
T. Bravo         6-1     10.0   93.2%     22.8%
T. Foxtrot       5-2     9.2    84.9%     24.8%
T. Hotel         5-2     8.3    56.2%     8.6%
T. Charlie       4-3     8.0    52.5%     12.7%
T. India         2-5     5.7    8.5%      2.1%
T. Juliet        2-5     5.6    5.2%      0.8%
T. Alpha         3-4     5.7    3.6%      0.5%
T. Delta         1-6     4.0    0.1%      0.0%
T. Golf          1-6     3.3    0.1%      0.0%

Team Alpha is 3-4 and behind two 2-5 teams in playoff odds. That is correct, and the reason to simulate rather than extrapolate a record: Alpha's roster projects worse than either of theirs, and seven weeks is enough for that to matter more than one game of standings.

How it works

Four layers, one direction of dependency:

  mcp/        thin adapters: decode args → call domain → render → return
    │         (no business logic, no arithmetic, no I/O)
    ▼
  render/     domain objects → compact text / small structured models
    │
    ▼
  domain/     PURE: models, optimizer, simulation, valuation, trades
    ▲         (no I/O, no network, no MCP imports, no clock, no randomness
    │          except through an injected Generator)
  providers/  ALL I/O: espn-api, Sleeper over httpx2, disk cache

providers/ builds domain objects and hands them upward. domain/ never reaches down. That is what makes the interesting code, the optimizer and the simulator, testable in milliseconds with no network and no MCP, and it is enforced rather than asserted: tests/test_layering.py walks the AST of every module under domain/ and fails if one of them imports mcp, httpx2, httpx, espn_api, requests or ffmcp.providers.

Upstream payloads never reach the model. Sleeper's player document is 14.6 MB. It is fetched at most daily and reduced to an id→{name, pos, team} index on write. ESPN league payloads are cached with TTLs that follow how fast the underlying truth moves (league settings 24 h, rosters 10 min, live scores 60 s) and projected into narrow domain models before anything is returned. Startup does no network at all, so tools/list answers immediately.

Request lifecycle: a single tool invocation flows through resolving settings and the league handle from context, fetching upstream data (cached, TTL by volatility), calling pure domain code, and rendering the result. The adapter decodes args and orchestrates. domain/ never knows about MCP, ESPN, or credentials.

Error handling: errors are short (one or two lines, never stack traces). A redact() helper strips secrets from every message and log line. When upstream fails and cache holds an expired entry, serve the stale data and say so: "cached 14m ago; ESPN unreachable" is far more useful than an exception. See docs/architecture.md for the full architecture.

Token efficiency

Response cost here is designed, measured, and regression-tested like any other engineering property. src/ffmcp/budgets.py is the single source of truth for the per-tool budgets. tests/test_token_budgets.py asserts every tool at every detail level against them and fails CI on a regression. uv run poe bench regenerates the table below from real fixture output, and CI fails if the committed table has gone stale.

Three rules do most of the work. Return conclusions, not data: optimize_lineup returns the swaps, not the roster. Default to the cheapest useful detail: every list-shaped tool takes detail: "compact" | "standard" | "full" and defaults to compact. Pick one channel per payload shape: the SDK derives structuredContent from the return annotation and emits a text block, and both reach the model, so lists return str with structured_output=False while small decision-shaped results (LineupAdvice, TradeVerdict) return Pydantic models where the schema earns its keep. That last one is a measured trade-off, not a preference: for a 15-row table, carrying both channels is close to double cost for no gain.

Every row's naive comparison is against the full fixture league payload (a 10-team league snapshot, standing in for a real upstream fetch) serialized as-is, rather than the reduced, narrow response above it. tokens is the deterministic local estimator. upstream bytes/tokens-if-naive are the same for every row because this benchmark runs against one fixture league. A live league's numbers vary by roster size and week, but the shape of the reduction does not.

The naive column is the honest comparison: it is what a passthrough server would spend to let the model answer the same question itself. The reduction runs from 140× to nearly 900×, and the answer is also correct, which the passthrough version would not reliably be.

tokens comes from a deterministic local estimator so CI needs no API key and no network. The estimator's error against Anthropic's real token-counting endpoint has not been measured, since this environment had neither the optional anthropic package nor a key. This functionality will be added in the future if requested.

The optimizer

See: src/ffmcp/domain/optimizer.py.

Assign rostered players to starting slots to maximize total projected points, where each slot admits a set of positions (RB/WR/TE takes a back, receiver or tight end), each player fills at most one slot, and each slot holds at most one player.

Greedy is wrong, and provably so. The obvious algorithm, walking the slots in order and dropping the best eligible player into each, strands position-locked slots. ESPN declares its RB/WR flex before the locked WR slot, so a greedy pass hands the flex the receiver the locked slot needed and backfills WR with whatever is left. The concrete counterexample is the first test in the file, written before the module was:

Nine points, on a two-slot roster, from an algorithm that looks obviously fine. On a real lineup the gap is smaller and much harder to notice, which is worse.

So it is solved exactly, as a maximum-weight bipartite matching: the Hungarian method in its successive-shortest-augmenting-path form with dual potentials, O(n²m) for n slots and m candidates. At roster scale (n ≈ 10, m ≈ 16) that is microseconds, which is what makes it affordable to call it thousands of times inside the trade search. Hand-written, about sixty lines of matching, no scipy. greedy() is kept in the module purely as a test baseline, marked as such, so the gap stays measurable: a property test asserts optimal ≥ greedy across 1,000 randomized rosters.

Every slot is also offered a zero-weight "leave it empty" option, which is what lets a roster too thin or too injured to fill the lineup produce a valid partial lineup instead of an error. Ties break by player id, so output is stable across runs.

Simulation

src/ffmcp/domain/simulate.py runs the rest of the season as a vectorized numpy Monte Carlo: each team's weekly score is drawn from a distribution whose mean is its optimal-lineup projection and whose variance comes from position-level dispersion. That variance model is documented in the module as an assumption, because it is one.

Why Δ win-probability instead of Δ points. "This lineup change is worth 10.8 points" is not the question. The question is whether it wins the week and the season, and the answer depends on the opponent, the schedule and the standings. A 10-point gain is decisive in a close matchup and irrelevant in a blowout, and only a simulation knows which one you are in. So optimize_lineup reports both, and find_trades ranks on odds.

Common random numbers: comparing two scenarios by running two independent simulations would bury a one-point lineup gain under sampling noise. The difference you are trying to measure is far smaller than the standard error of either run. So win_prob_delta draws a single (n_sims, n_weeks, n_teams) noise array and evaluates both scenarios against it. The scenarios then differ only by the change under test, and the noise cancels in the difference. This is the non-obvious technique in the file and it has a test that is the argument for it: the delta for a strictly better lineup must be positive in ≥ 95% of 100 seeds, while the same comparison with independent draws is measurably noisier.

Everything is seeded through an injected numpy.random.Generator. No module-level global random state, so runs are exactly reproducible. 10,000 sims for a 12-team league finish in under two seconds, and the work runs in asyncio.to_thread with progress reported via ctx.report_progress().

Modern MCP

Built against MCP spec 2026-07-28 and Python SDK 2.x (MCPServer), not the v1 FastMCP API that most training data describes. What that buys, and where to look:

And, as deliberately, what is not used:

Knowing what a spec revision deprecated is a stronger signal than using every feature it kept. That table was built by introspecting the installed SDK (mcp==2.2.0) directly, not recalled from memory, since most MCP examples online still target the superseded v1 FastMCP API.

Configuration

Secrets are typed SecretStr, and errors.py:redact() strips anything cookie-shaped from every error message and log line at the boundary (unit-tested against a fake espn_s2 and a SWID GUID). See the Quickstart above for where to find ESPN cookies.

Testing

uv run poe check    # ruff lint + format, mypy --strict, pytest, benchmark freshness

146 tests, no network anywhere: fixtures for ESPN, httpx2.MockTransport for Sleeper. Beyond the usual, the suite carries a few tests that exist to turn claims into facts: the layering purity check, the greedy-vs-optimal counterexample, the common-random-numbers comparison, the token budgets, and a hygiene test asserting no fixture contains a real league id or anything cookie-shaped.

The demo league itself is synthetic (invented players, invented projections), generated deterministically by scripts/make_demo_fixture.py and committed, so that shipping a runnable demo does not mean publishing anyone's real roster. scripts/record_fixtures.py is the other path, for anonymizing a real league you have consent to use.

One gap, stated rather than hidden: the surface has been exercised end-to-end over real stdio and through an in-process mcp.Client, but not yet by hand through a GUI client.

Docker

docker build -t ffmcp .
docker run -p 8000:8000 -e FFMCP_MODE=demo ffmcp        # no credentials
docker run -p 8000:8000 --env-file .env ffmcp           # real league

Slim, non-root, streamable HTTP only: stdio does not make sense across a container boundary.

License

MIT