espn-ff-manager

An MCP server for managing an ESPN fantasy football team after the draft: waivers, lineups, injuries, trades, playoff odds, and K/D:ST streaming.

Built on espn-api (unofficial ESPN API wrapper). Read-only: it never makes roster moves on your ESPN account.

Security design

• Credentials never pass through the model. Your espn_s2/SWID cookies are read from the environment or a .env file — there is deliberately no authenticate tool, so cookie values never appear in chat history.
• Credential values are redacted from error messages before they reach the model.
• The league ID is pinned in config, not accepted from the model.

Tools

Tool	What it does
get_league_overview	Settings, standings with divisions, current week
get_roster	Any team's roster with projections and injury status
get_matchup	Full box score: starters, bench, actual vs. projected
get_free_agents	Top available players with weekly + ROS projections
optimize_lineup	Optimal legal lineup vs. your current one, with start/sit moves
get_injury_report	Injured / questionable / bye-week players on a roster
get_recent_activity	League transaction feed (adds, drops, trades)
analyze_trade	Rest-of-season projection deltas for both sides of a trade
get_playoff_outlook	Monte Carlo playoff odds from scoring profiles + schedule
get_streaming_targets	Best available K or D/ST for a week vs. yours
get_waiver_targets	Free agents ranked by upgrade over your weakest player
get_draft_board	Deterministic VORP draft board with tiers, from your league's real slots
refresh_league	Force-refresh cached league data (default TTL 15 min)

optimize_lineup also reports per-slot margins and contested slots (close calls or injury-flagged starters) — useful as the escalation trigger for agent-based start/sit research. Before the season starts it degrades to season-average projections instead of erroring.

Headless report CLI

The same data is available as plain JSON on stdout, for cron jobs and agent scripts that don't speak MCP:

uv run python -m espn_ff_manager.report league
uv run python -m espn_ff_manager.report lineup [--week N]
uv run python -m espn_ff_manager.report draft-board [--size N]
uv run python -m espn_ff_manager.report free-agents [--position RB]
uv run python -m espn_ff_manager.report history --year 2025

Setup

Requires uv (which manages Python for you).

cd espn-ff-manager-mcp
cp .env.example .env   # then edit .env with your league ID + cookies
uv sync
uv run pytest          # optional: run the test suite

Register with Claude Code

claude mcp add espn-ff -- uv --directory /path/to/espn-ff-manager-mcp run espn-ff-manager

Register with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Notes

• ESPN has no official public API; this uses the same unofficial endpoints as the espn-api library and can break without notice when ESPN changes things.
• Weekly projections come from ESPN's own projection feed.
• analyze_trade ROS math covers the regular season only; check playoff-week schedules separately before accepting a trade.

License

MIT