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,
  "playoff_odds_delta": 0.3,
  "win_probability": 34.8,
  "strategy": null,
  "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 and this week's win probability, about 150 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/jeremylach2/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: espn-ff-manager

What it does

Thirteen 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)
Injuries: S. Quintero (O), L. Novak (I)
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, a 34.8% chance of beating this week's opponent, and +0.3 points of playoff odds. analyze_matchup prices the week:

Week 8 (proj): Team Alpha 106.1 vs Team India 118.6 — 35% win prob
Biggest edges:
  RB: Team India +25.9
  K: Team Alpha +8.8
  WR: Team Alpha +4.8
Swing player: D. Rios (WR GB, ±12.6 pts)
Stakes: win -> 4% playoff odds, loss -> 0% (3-pt swing)

Stakes is one simulation of the season split by how this week's game went, so it answers "how much does this game matter" rather than "how likely am I to win it". Alpha is nearly eliminated, so the answer is: not much. A bubble team in week 12 sees 20-point swings.

Win probability, not points. optimize_lineup maximises the chance of beating this opponent, which is not always the same lineup as the most projected points. With your score and theirs both roughly Normal, P(win) = Φ((μ − μₒ) / √(σ² + σₒ²)): an underdog raises it by raising σ, a favourite by lowering it. So the optimizer re-runs the exact matching with each player scored mean + tilt × sd for a handful of tilts, keeps whichever lineup truly wins most often, and explains itself in strategy whenever that costs projected points. An honest note on how often that happens: in a real 16-team league in week 3 it changed none of 16 lineups. Spread is nearly proportional to projection, so tilting rescales two same-position players together and cannot reorder them; it bites only when two close players' spreads genuinely differ, which mostly means one projection the sources dispute. The feature is cheap, correct, and occasionally decisive, and it is described here as exactly that.

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 [lucky] (id 2): give Q. Hargrove / get B. Battaglia, M. Quintero — me +39.1pts, them +12.4pts, +3.7% odds — Strengthens RB by 8.0 started pts/wk.
Team Bravo [lucky] (id 2): give L. Petrov / get L. Castellan — me +35.1pts, them +25.5pts, +2.9% odds — Strengthens RB by 9.8 started pts/wk.
Team Bravo [lucky] (id 2): give Q. Hargrove / get C. Castellan — me +21.9pts, them +23.9pts, +2.9% odds — Strengthens RB by 6.7 started pts/wk.
Team Bravo [lucky] (id 2): give L. Petrov / get B. Battaglia, T. Obi — me +38.1pts, them +1.6pts, +2.6% odds — Strengthens RB by 8.0 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.

Points are priced week by week over the rest of the season, not as this week's value times the weeks left: each player is absent in his own bye week, later weeks use his season-average projection rather than this week's matchup, and the playoff weeks count in proportion to each side's playoff odds. Offers that are the same core swap with a different sweetener are collapsed into one, and the partner's tag ([lucky], [unlucky], [inattentive], from power_rankings) says what their record is hiding.

evaluate_trade prices one named offer from both sides:

{
  "verdict": "lean_accept",
  "my_value_delta": 21.9,
  "partner_value_delta": 23.9,
  "my_playoff_odds_delta": 2.9,
  "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    ROS    DROP
D. Ivanov        RB   CIN 12.4  +4.0   +19    T. Moreau
C. Fairbanks     WR   KC  13.1  +2.7   +17    T. Moreau
ARI D/ST         D/ST ARI 8.8   +2.1   +6     WSH D/ST
I. Battaglia     WR   CHI 10.6  +0.2   +2     T. Moreau

Caleb Fairbanks is the higher projection. Devin Ivanov is the better pickup, because this roster is thin at running back and deep at receiver. VAL is this week; ROS is the whole move, add and drop, over the rest of the calendar. The two disagree more than you would guess: in a live league the best defense to stream this week was worth +3.4 now and +9 for the season, while one projected 0.2 lower was worth +36, because its good matchup was not a one-off.

An earlier version of this table told Team Alpha to drop Tariq Whitlock, the roster's hottest receiver, for every pickup. He is on bye this week, so his projection was zero, and cuts were ranked by this week's projection. They are now ranked by rest-of-season rate.

When the roster starts a lead running back, a Handcuffs: line names the teammate who inherits his work if he goes down (the back playing the most snaps behind him) and where that player is: free agent, your bench, or another roster.

Who is due to regress?

Points are volume times efficiency times touchdown luck, and only volume holds up week to week. buy_low_sell_high prices every player-game by its opportunity alone (targets, carries, air yards, pass attempts) as expected points, and treats the gap to actual points as luck:

Sell high (yours, scoring above their workload):
PLAYER           POS  TM  OWNER          G  SNAP XPPG  PPG   LUCK
T. Whitlock      WR   SEA Team Alpha     7  88%  9.2   15.3  +6.0
Hold, do not sell low (yours, due to improve):
PLAYER           POS  TM  OWNER          G  SNAP XPPG  PPG   LUCK
L. Petrov        QB   LAC Team Alpha     7  100% 23.0  12.5  -10.5
Buy low (other rosters):
PLAYER           POS  TM  OWNER          G  SNAP XPPG  PPG   LUCK
J. Quintero      WR   GB  Team Charlie   7  88%  18.2  11.9  -6.3
T. Delgado       QB   BAL Team Foxtrot   6  100% 23.2  17.0  -6.2
T. Osei          WR   KC  Team Bravo     7  88%  18.6  12.5  -6.2
D. Thackeray     QB   DET Team India     6  100% 21.3  15.3  -6.0
L. Ellington     WR   DET Team Golf      6  88%  15.3  9.7   -5.7
Buy low (free agents):
  none

That is a claim about the future, so it was tested on one: fit on 2024, scored on 2025. Expected points per game through week 4 predicted the next six weeks with a mean absolute error of 3.44 points, against 3.69 for actual points per game. Players 3+ points per game below their expected points went on to score +3.5 more per game; players 3+ above gave back 2.9. The ±3 threshold is where that regression was measured, and labels wait for three games (before that, the tool shows the biggest gaps as a watch list, and says so).

One player, in depth

Damon Rios — WR GB, week 8
Projected: 15.9 pts (range 0.0-32.1, p10-p90)
Second opinion: Sleeper 8.7; sources disagree by 45%, so the range is wider
Status: healthy · bye week 9
Value over replacement: +3.7 pts/wk, +22.4 pts rest of season (6.1 wks, byes and playoff odds counted)
Usage (7 g): 62% snaps (last 62%), 9.7 tgt/g (28% share), expected 16.6 vs actual 15.0 pts/g
Game: GB implied 23.0 pts (-1.0 vs WSH, total 45.0)
Market: 96% owned

Game is the betting market's implied team total (total ÷ 2 − spread ÷ 2), from The Odds API when a key is configured. It is context, never an input: ESPN's projection already prices the matchup, and adding Vegas on top would count the same information twice.

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 a 2-5 team in playoff odds. That is correct, and the reason to simulate rather than extrapolate a record: Alpha's roster projects worse, and seven weeks is enough for that to matter more than one game of standings.

Who is actually good?

A record is a noisy measure of a team in head-to-head fantasy, because the schedule decides who you play on the week you score 140. power_rankings scores every team against every other team every week (all-play), calls the gap to actual wins luck, and grades each manager's lineup decisions separately from the dice:

Power rankings after 7 weeks (by all-play record):
RK  ID  TEAM           W-L   ALLPLAY LUCK  PPG    LINEUP% BENCH
1   5   Team Echo      6-1   53-10   +0.1  126.7  96%     15.7
2   2   Team Bravo     6-1   42-21   +1.3  117.8  100%    8.9
3   8   Team Hotel     5-2   40-23   +0.6  114.6  100%    13.0
4   6   Team Foxtrot   5-2   36-27   +1.0  115.2  100%    15.8
5   9   Team India     2-5   35-28   -1.9  111.3  100%    12.6
6   3   Team Charlie   4-3   29-34   +0.8  109.8  100%    11.7
7   1   Team Alpha     3-4   28-35   -0.1  96.7   100%    13.3
8   10  Team Juliet    2-5   23-40   -0.6  102.2  100%    16.9
9   4   Team Delta     1-6   16-47   -0.8  93.6   100%    17.0
10  7   Team Golf      1-6   13-50   -0.4  93.9   100%    11.2
Team Echo: inattentive
Team Bravo: lucky
Team Foxtrot: lucky
Team India: unlucky

LINEUP% is projected points started over the best lineup by the projections of the day. The obvious alternative, actual points over the best lineup in hindsight (the BENCH column, as points per game), was measured on a real league and is mostly noise: a manager with 99.8% lineup accuracy scored 83% of hindsight-optimal, because nobody knows which receiver will boom. Lineup accuracy behaves like a trait instead: the same manager lagged the league in both 2025 and 2026. Team India, 2-5 with the fifth-best all-play record, is the team to trade with.

How far should I trust the projections?

Projection error in this league, weeks 1-7 (mean absolute error, pts):
POS  N     ESPN  SLEEPER AVG   BIAS
QB   130   6.24  6.38    6.29  -0.99
RB   329   4.82  4.86    4.83  +0.17
WR   338   4.76  4.79    4.75  -1.27
TE   129   4.59  4.48    4.52  -0.42
K    65    3.65  3.74    3.69  -0.13
D/ST 68    5.98  5.90    5.93  +0.54
ALL  1059  4.95  4.98    4.95  -0.50
ESPN is closer by 0.03 pts/player-week. Differences under ~0.3 are noise at this sample size; where the sources disagree, trust both less.
Biggest disagreements on your roster this week: D. Rios 15.9 vs 8.7

Measured, not assumed

This project started from a hunch, that ESPN's projections were the problem, and a list of features that followed from it. Before building any of them, every one was tested against a real 16-team league's full 2025 season (about 3,000 player-weeks of ESPN projection beside actual score) and, for expected points, against nflverse play-by-play for 2024 and 2025. Half of them survived. scripts/calibrate.py reproduces every number here and every fitted constant in domain/.

The variance change matters most, even though it is the least visible. The old model overstated every lineup's weekly spread by nearly half (33 points against a real 22), which pulled every win probability toward 50% and understated how much a better lineup, trade or pickup was worth. Its one-standard-deviation band caught 86% of real team-weeks; a calibrated band should catch 68%, and the measured model's catches 69%.

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 domain/variance.py: per-position spreads measured on a real league's season, widened for players whose projection sources disagree (see Measured, not assumed).

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, and any apiKey= query parameter, from every error message and log line at the boundary (unit-tested against a fake espn_s2, a SWID GUID and a key-bearing URL).

Every signal beyond ESPN is optional and degrades to a one-line caveat rather than an error: no odds key means no Game line; Sleeper or nflverse being down means ranges from position spreads alone, or no usage section. A tool that refused to set a lineup because GitHub was slow would be worse than one that sets it with slightly less information and says so. See the Quickstart above for where to find ESPN cookies.

Testing

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

230 tests, no network anywhere: fixtures for ESPN, httpx2.MockTransport for Sleeper, nflverse and The Odds API. 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, a star on his bye week never being the roster cut, one good matchup never being extrapolated across a season, 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. Its history, usage, second-opinion projections and betting lines come from scripts/make_demo_insights.py, derived from that league so the two agree: each team's starters add up to the scores its standings were built from. 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, needs FFMCP_AUTH_TOKEN too

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

A live-mode server refuses to start over HTTP without FFMCP_AUTH_TOKEN set (see .env.example) — with no auth layer, an internet-reachable endpoint would let anyone who found the URL read your real league through the tools. Every request must then carry it back as Authorization: Bearer <token>. Demo mode skips this: it only ever serves synthetic fixtures, so an open demo endpoint is harmless and is the easiest way to let someone try the server without configuring anything.

Deploying publicly for free

Render's free web service tier needs no credit card, builds straight from this repo's Dockerfile, and gives you a public HTTPS URL. The tradeoff: a free instance sleeps after 15 minutes idle and takes 30-50s to wake on the next request, which is fine for a tool an agent calls occasionally.

1. Push this repo to GitHub (or use your fork).

2. On Render: New → Web Service, connect the repo, environment Docker. Render detects the Dockerfile automatically; leave the build/start commands blank.

3. Set environment variables under the service's Environment tab:

   • FFMCP_MODE=live, FFMCP_LEAGUE_ID, and (private leagues only) FFMCP_ESPN_S2 / FFMCP_SWID — same as .env.example.

   • FFMCP_AUTH_TOKEN — generate one locally with python -c "import secrets; print(secrets.token_urlsafe(32))" and paste it in. The server will not start without this in live mode.

   • Leave PORT alone; Render injects it and the container's entrypoint binds to $PORT automatically (falling back to 8000 only when it's unset, e.g. a plain local docker run).

4. Deploy. Point any Streamable-HTTP MCP client at https://<your-service>.onrender.com/mcp with header Authorization: Bearer <your token>.

Rotate the token (just change the env var and redeploy) if it ever leaks — there is no session or expiry on it otherwise.

License

MIT