krmisystems/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.
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.
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:
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.