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.

Related MCP server: yahoo-fantasy-mcp

Tools

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