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 manual recovery. A live Ravens D/ST selection succeeded. The record does not establish which autocomplete branch ran.

The live draft trial completed a 16-player roster in a 10-team PPR snake draft. It recorded 13 manager-confirmed picks and 3 ESPN Autopicks. Startup failures and an autocomplete timeout caused platform fallback selections. The run required compatibility patches and manual recovery. It was not an unattended draft from start to finish. Its runtime used installed v0.2.1 dependencies with changing working-tree patches. Do not attribute that live result to an unchanged released wheel.

The third draft trial also finished with 13 manager-confirmed picks and three platform fallbacks. It exposed team-name whitespace and D/ST selector failures. Version 0.3.1 fixes both cases in isolated Chrome tests. The browser handoff missed the final two turns. This trial also required operator recovery.

Keep team management running

espn_start_automation runs inside the MCP process. Use espn_start_standalone_worker for a local worker that continues after Codex closes while that computer remains available.

For operation without the client PC, install the season coordinator on a server. The HTTP coordinator uses a protected server session file and visits configured teams serially. It runs without the client PC, a Chrome process, or a display service. Each team keeps a separate SQLite database, policy, scoring week, and pending claims. A lease prevents simultaneous HTTP control of the same team through the same session directory. Health separates process activity, observation freshness, analysis readiness, and action readiness. The optional PostgreSQL archive exports bounded batches and commits checkpoints with the evidence. Private backups preserve the operational databases and configuration.

The deployed v0.4.0 coordinator's first sweep returned fresh HTTP observations for all five teams. Four teams had current analysis and required no lineup change. One team had incomplete tight-end coverage with an unknown projection. Health correctly reported degraded analysis. That initial sweep submitted no live transaction and preserved existing team policies.

The user then authorized an exact coverage repair with temporary action limits. Two unchanged automatic engine steps confirmed a free-agent add/drop, then a lineup exchange, through authenticated HTTP. Both actions received ESPN EXECUTED receipts and matching roster observations. The previous starter remained on the bench. Other roster players, starter assignments, and pending transactions stayed unchanged. The original policy was restored after execution. Read HTTP season acceptance for the deployment, package checks, and remaining live acceptance.

After the fifth draft, the v0.3.2 server verified fresh Week 1 observations, selected-team locks, and current lineup calculations for five exact team contexts. The verified handoff recorded zero new lineup authorizations and zero unresolved authorized claims. Those v0.3.2 observations did not verify live server lineup submission or an unattended season. Read server acceptance for restart, archive, and recovery evidence. All three additional draft trials are complete, with their failures and execution sources recorded separately. Five-team season outcomes and uninterrupted season operation remain unverified.

Install from PyPI

Version 0.4.0 adds HTTP season transactions, the portfolio MCP, and the Fieldroom dashboard. The base HTTP installation needs no browser. Install the browser extra for live drafts.

Version 0.3.3 expands the descriptions, input schemas, and behavior annotations for all 30 MCP tools. Read the tool definition review for compatibility checks and external scoring status. Version 0.3.2 preserves verified opponent draft history when a season projection is missing. Version 0.3.1 fixed draft team-name whitespace and D/ST selectors. Version 0.3.0 introduced server season scheduling, durable evidence, and a PostgreSQL archive. Check the PyPI project and distribution status for available releases. The manager has an active MCP Registry record. Use Python 3.11 or later and uv. The published v0.3.3 browser workflow also requires installed Google Chrome.

uv tool install fantasy-football-manager==0.4.0
fantasy-football-manager --help
fantasy-football-espn --help
fantasy-football-portfolio --help
fantasy-football-dashboard --help

Install from source

For development, run these commands from the repository checkout:

uv sync --locked --dev
uv tool install --force .
fantasy-football-manager --help
fantasy-football-espn --help
fantasy-football-portfolio --help
fantasy-football-dashboard --help

Connect the commands

Register both commands with Codex, or use the Codex plugin instructions:

codex mcp add fantasy-football-manager -- fantasy-football-manager
codex mcp add fantasy-football-espn -- fantasy-football-espn

Both commands must be on the MCP host's PATH. Restart the MCP connection after installation. The plugin already registers both commands. Avoid duplicate direct registrations when using it. The plugin contains workflow instructions and command registrations; it does not install the Python package.

Use the same FFM_DATA_DIR or --data-dir for both MCP servers that manage one league. For v0.4.0 HTTP operation, configure FFM_ESPN_CREDENTIAL_FILE on the MCP host. The base HTTP runtime requires neither Chrome nor Playwright. For draft or legacy browser operation, install the browser extra and Google Chrome. Use FFM_BROWSER_DATA_DIR to select a shared browser profile root across separate league databases. Browser mode accepts an optional cdp_url for an explicit loopback browser debugging endpoint. Keep profiles, credentials, databases, logs, and real league exports outside Git. Read the privacy notes.

Use the v0.4.0 release page for the versioned wheel, plugin ZIP, and checksums. The distribution acceptance record tracks verified GitHub, PyPI, and MCP Registry publication separately. Follow the release instructions for publisher setup. Earlier published assets remain unchanged.

Scope and validation

The v0.4.0 local suite passed 1,048 tests with 22 skips. A separate PostgreSQL run passed 92 archive tests. A fresh base installation passed actual STDIO checks for 17 manager tools and 16 ESPN tools without Playwright. All 28 deployed Python files matched the reviewed wheel. Existing dependency versions and team policies remained unchanged. One authorized repair subsequently verified automatic HTTP add/drop and lineup execution in a single Week 1 context. Live waiver processing, IR moves, and scoring-week rollover remain Not Tested. Read HTTP season acceptance for the exact evidence boundary.

The v0.3.3 source passed 664 tests across the base and separate Chrome runs, including 17 isolated Chrome cases. Two remaining skips required PostgreSQL configuration and Windows symlink permissions. All seven v0.3.3 source CI jobs passed, including Windows, Ubuntu, Chrome, and PostgreSQL checks. These test counts are distinct from live account acceptance. Live draft execution of an installed v0.3.3 wheel remains Not Tested. See validation status, server acceptance, and the compatibility matrix.

For a synthetic demonstration, run uv run fantasy-football-manager --demo. The CLI demo calculates an in-memory report. The manager's demo execution tools modify synthetic state only. Use a separate state directory for demonstrations.

For development checks, run:

uv run pytest -q
uv run python scripts/validate_release.py

Browser and PostgreSQL cases require their explicit test settings. Use the complete test commands. Release packaging waits for the requested commit's Windows, Ubuntu, Chrome, and PostgreSQL gates. See architecture, policy, and release instructions. The discovery measurement plan separates publication checks from observed discovery results. The repository's distribution check reports GitHub and Glama state after updates and each day. It records release gaps and unknown build evidence without publishing or requesting a rebuild.

The Codex catalog package uses validated root metadata and generated plugin files.

License: MIT. Copyright 2026 krmisystems.