mcp-fleaflicker

An MCP server for Fleaflicker fantasy leagues. It reads rosters, standings, matchups, boxscores, and draft boards, and it scores stat lines using the league's own published scoring rules rather than a hardcoded scoring system.

Fleaflicker's read API is public and unauthenticated, so this server needs no API key, stores no credentials, and exposes no write surface. It cannot change your league.

Why the scoring engine is the interesting part

Most fantasy tooling hardcodes a scoring system, or offers a handful of presets. This server fetches FetchLeagueRules and evaluates whatever it finds, so the same code scores a 6-point-passing-TD superflex league and a standard half-PPR league without a branch.

Three things about Fleaflicker's rule model are load-bearing, and each was verified against the live API rather than assumed:

Zero-valued fields are omitted from the JSON. The API is protobuf-derived and serializes defaults by leaving them out. The shutout rule ("10 extra points when total Points Allowed is exactly 0") arrives with no boundLower and no boundUpper key, because both are 0. Default a missing upper bound to infinity and every defense scores the shutout bonus every week. Missing bounds mean zero, never "unbounded".

RANGE_LOWER_BOUND is two different rules wearing one name. Which one depends on category.multiValue. On a single-valued category it is a once-per-game threshold on the summed total (300 passing yards is +1, once, no matter how far past). On a multi-valued category it fires once per qualifying event (every touchdown of 80+ yards is +4 each).

A touchdown is two categories, not one. The flat 6 points and the long-distance bonus live under separate category ids that share a name within a group. They are linked automatically by (group, name), so one caller-supplied stat key feeds both.

Score one game at a time

Every threshold rule fires on a single game's box score. A receiver with 2,000 yards across 17 games earns the 150-yard bonus only in the games he actually cleared 150. Feeding the engine a season total silently miscounts every bonus in the rule set.

Ambiguous stat keys fail loudly

"Interception" is a passing category worth −2 (the quarterback threw it) and a defensive category worth +2 (the defense caught it). Resolving a bare interception to both nets two picks to exactly zero and reports a confident, wrong number. So any key reaching more than one scoring group refuses to resolve and names the alternatives instead: passing_interception and defense_interception.

Related MCP server: Sleeper MCP Server

Tools

All tools are read-only and idempotent. Every tool returns a JSON string in one of two shapes:

// success
{"data": ...}

// failure — code is from a fixed enum
{"error": "human-readable message", "code": "UPSTREAM_DOWN", "details": {...}}

Codes: UPSTREAM_DOWN, AUTH_FAILED, INVALID_INPUT, NOT_FOUND, RATE_LIMITED, INTERNAL. No exception ever reaches the caller.

Quick start

git clone https://github.com/pete-builds/mcp-fleaflicker.git
cd mcp-fleaflicker
cp .env.example .env          # set FLEAFLICKER_LEAGUE_ID, or leave it blank
docker compose up -d --build
curl -s localhost:3727/healthz

Then register it with your MCP client:

claude mcp add fleaflicker --transport http --scope user \
  --url http://localhost:3727/mcp

Running from source instead:

python -m venv .venv && .venv/bin/pip install -r requirements-dev.in
.venv/bin/python server.py

Finding your league id

It is in the league URL: fleaflicker.com/nfl/leagues/14153 is league 14153.

Setting FLEAFLICKER_LEAGUE_ID makes every tool's league_id argument optional. Leaving it unset is also valid: callers then pass league_id per call, which is how one deployment serves several leagues.

Configuration

Scoring examples

Get the valid stat keys first:

get_league_rules()  ->  data.scoring.stat_keys

A plain number is a count or total. A list is per-event yardage, which is what distance bonuses need:

score_stat_line(
    stats={"passing_yard": 318, "passing_td": [45, 12], "passing_interception": 1},
    position="QB",
)

That is two passing touchdowns, one of 45 yards and one of 12: the flat rule scores twice and the 40-to-79 bonus once. Passing {"passing_td": 2} instead scores the flat rule and reports the distance bonus under unresolved_bonuses, rather than silently scoring it as zero.

The response carries the arithmetic, not just the total:

{"data": {
  "position": "QB",
  "total": 31.52,
  "breakdown": [
    {"category": "passing_yard", "kind": "linear", "points": 8.72,
     "detail": "218 / 25 x 1", "rule": "1 point for every 25 Passing Yards (0.04 per)"},
    ...
  ],
  "unscored_keys": [],
  "unresolved_bonuses": []
}}

Testing

.venv/bin/python -m pytest -q     # 121 tests
.venv/bin/ruff check .

Fixtures under tests/fixtures/ are real captures from the live API, trimmed to the fields the code reads. They are real rather than hand-written on purpose: the behaviours that bite here — omitted zero fields, one touchdown spanning two category ids, a bonus whose bounds are both absent — are exactly the ones a hand-written fixture would smooth over.

The scoring tests include oracle tests that reconstruct real stat lines and assert against the totals Fleaflicker itself published for those games, so the engine is checked against the platform rather than against its own arithmetic.

What this does not do

It reads and scores; it does not project. There is no ranking model, no waiver recommendation, and no start/sit advice. Feeding projected stat lines into score_stat_line gives you projected points under the real rules, but the projections have to come from somewhere else.

It is also unofficial and not affiliated with Fleaflicker. The API it uses is public but undocumented, so a shape change upstream can break a normaliser; the tests are built to catch that quickly.

License

MIT. See LICENSE.