Fantasy Football Manager

ESPN fantasy football team management for Codex and other Model Context Protocol (MCP) clients. Season operations use authenticated HTTP without Chrome or Playwright. Connect your league, sync its roster, and calculate a legal weekly lineup from current projections. The same package provides a draft assistant with continuous Monte Carlo simulations and a server coordinator for multiple teams.

The manager MCP server provides 17 tools for analysis, policy, and league state. The ESPN MCP companion provides 16 tools for live observations, controlled transactions, and continuous operation. The portfolio MCP adds five tools for all configured teams, players, saved proposals, and lineup analysis. HTTP season actions include lineups, free-agent additions, waiver claims, drops, and IR moves. Draft support retains the existing browser adapter.

Version 0.4.0 preview: The reviewed v0.4.0 wheel is deployed privately and has completed a five-team HTTP observation sweep. An explicitly authorized coverage repair also confirmed two automatic HTTP actions: a free-agent add/drop and a subsequent lineup exchange. Version 0.3.3 assets retain their earlier behavior. See the release links below for the v0.4.0 preview. Read HTTP season acceptance for the current evidence and remaining live validation. Read Stable release readiness for scheduled acceptance checks, backup verification, and release gates.

This independent project requires your ESPN account. A protected session file supplies HTTP authentication. An optional Linux import reads only the two ESPN session cookies from an existing profile without starting a browser.

Try a fictional lineup

Run this demo with Python 3.11 or later and uv. It requires no ESPN account, Chrome session, or MCP client.

uvx --from fantasy-football-manager==0.4.0 fantasy-football-manager --demo

The command prints a fictional lineup report and exits without changing saved league state. The verified demo returns status: "ok", live_actions: false, and a projected improvement of 5.50 points. These values describe synthetic inputs, not a measured fantasy result.

Read the developer showcase for the design, verified trials, and contribution ideas.

Open the team dashboard

The source checkout includes Fieldroom, a local dashboard for multiple managed teams. Inspect rosters, source health, projections, action limits, and proposed changes in one workspace. Optional approval controls submit exact saved HTTP season proposals through the existing transaction service.

uv sync --locked
uv run fantasy-football-dashboard --demo --enable-actions

Open http://127.0.0.1:8765/. Demo approvals affect fictional in-memory records only. They make no ESPN requests. The dashboard requires no Node.js runtime, ESPN account, or external UI service. This dashboard is not included in the published v0.3.3 package.

Read the dashboard setup and API guide for actual team data and submission controls. Use the media UI integration prompt to connect an existing authenticated home-server interface. Football is the only implemented sport. The portfolio envelope leaves room for future adapters.

Start with a weekly lineup

HTTP roster reads have verified ownership and player locks across five team contexts. One authorized Week 1 repair verified automatic free-agent acquisition and a subsequent lineup exchange through the deployed candidate. Live waiver processing, IR moves, and scoring-week rollover remain Not Tested.

For the v0.4.0 source checkout:

uv sync --no-dev --extra session-import

1. Configure the protected session file with FFM_ESPN_CREDENTIAL_FILE.
2. Connect both MCP servers to the same per-team state directory.
3. Read the saved action modes with get_manager_config.
4. Call espn_connect with the league, team, season, phase="season", transport="http", and scoring week.
5. Call espn_sync to read current rosters, projections, locks, and pending transactions.
6. Call recommend_lineup to calculate a legal lineup.
7. Read espn_get_status before enabling the required action modes.

The HTTP setup guide explains credential permissions, supported imports, and renewal requirements. No ESPN credential values are MCP tool arguments. HTTP mode does not start a browser.

The result includes the legal lineup and estimated projection change when the required inputs are complete. Missing projections or lock evidence can prevent a recommendation or submission. Selected-team lock evidence does not establish league-wide power rankings.

flowchart LR
    Client[Codex or MCP client] --> Companion[ESPN MCP companion]
    Companion --> HTTP[Authenticated HTTP season adapter]
    HTTP --> ESPN[ESPN league]
    Companion --> Draft[Optional browser draft adapter]
    Draft --> ESPN
    Companion --> Claim[Durable transaction claim]
    Claim --> Verify[Observe and verify result]
    Companion --> State[Per-team SQLite state]
    Client --> Manager[Analysis and policy]
    State --> Manager
    State --> Archive[Incremental PostgreSQL archive]

Read the ESPN workflow and tool reference for configuration and submission steps. Check the versioned compatibility matrix for supported layouts, regression fixtures, and live evidence.

Choose how actions run

Use update_manager_config to replace the full config with its current revision. Read that config before changing one action mode. Strategy preferences do not grant execution permission. For lineup changes with approval, use review mode and confirm each exact proposal.

For season automation, connect through HTTP and configure the required action modes and limits. Then call espn_start_automation. Set auto_rollover=true to follow ESPN's verified current transaction period. An unresolved submission keeps its original week until reconciliation completes.

HTTP mode submits a complete legal lineup transaction. Legacy browser mode still verifies one exchange at a time. Acquisitions respect protected players, allowed drops, roster capacity, pending commitments, and league limits. A named coverage repair requires explicit saved authorization when its improvement cannot be calculated. Unknown projections remain null.

Each live submission receives a durable claim before the HTTP request or draft click. The service verifies the resulting ESPN state. An uncertain result blocks another submission until reconciliation. A pending_waiver result identifies a queued claim. Only observed ownership can confirm an acquisition. Use espn_stop_automation to pause new actions for that league's data directory. It does not undo an action already submitted.

Draft with continuous simulations

Install the browser extra for draft operations. Connect with phase="draft", then call espn_sync to verify complete history and the current pick. Set the requested draft strategy, action mode, and limits before calling espn_start_automation. Automatic submissions require the correct team on the clock and verified disabled ESPN Autopick.

The draft engine accounts for snake order, roster caps, starter completion, and five strategy preferences. It recalculates after input changes and combines completed simulation batches for unchanged inputs. Its estimates use a two-pick horizon, projected player values, and simulated opponent choices. Availability estimates are conditional. They do not guarantee that a player survives to the next pick. More trials do not correct stale inputs or projection errors. The model does not report championship odds.

The fifth draft trial completed with 13 manager-confirmed picks, two direct host-browser picks, and one unattributed selection. An opponent selection without a season projection blocked history normalization. The operator stopped the worker and completed the final two turns. The host capture contains all 160 selections and matches the 132 picks previously stored by the server. Installed v0.3.1 execution methods remained unchanged. This run required operator recovery and does not verify unattended completion. Version 0.3.2 separates verified opponent identity from projected value. Its regression evidence is separate from this live run.

The earlier fourth draft trial verified all 160 league selections and 16 manager-confirmed picks. It recorded zero ESPN Autopicks and zero host-browser DRAFT clicks. Installed v0.3.1 execution methods were unchanged. A private launcher handled collection and lifecycle.

One browser-control error occurred before the first authorization. A later check recovered before submission. The run required no package patches, restart, or ma