ESPN Fantasy Baseball — AI-Powered League Manager

Turn your H2H Categories league into a conversation. Scout opponents, find free agents, analyze trades, run your auction draft, and track your season — all through Claude.

"Who should I pick up at SS this week?"

Claude checks your roster, identifies your weak categories, searches free agents at SS, compares them against your current player, and recommends a pickup that flips two categories in your matchup.

Claude Code

<p align="center"> <img src="assets/demo-claude-code.gif" alt="Demo — Claude Code" width="700"> </p>

OpenClaw

<p align="center"> <img src="assets/demo-openclaw.gif" alt="Demo — OpenClaw" width="350"> </p>

What You Can Do

Weekly Management

• Matchup scouting — See your H2H category breakdown, identify swing categories, and get lineup recommendations to flip close ones
• Free agent search — Find pickups filtered by position, ranked by category impact (not generic points)
• Waiver wire alerts — Monitor league transactions, spot dropped players worth claiming
• Weekly prep — Full Monday briefing: matchup preview, injury report, start/sit decisions, streaming targets

Trades & Strategy

• Trade analysis — Evaluate any trade with a category-by-category impact table and a clear accept/decline verdict
• Category strategy — Map your strengths and weaknesses across all 14 categories, decide what to punt, and build a path to 8+ category wins per week
• Season outlook — Big-picture analysis: win/loss trajectory, playoff positioning, roster improvement plan

Auction Draft ($280 budget)

• Live draft board — Track every pick, price paid, and remaining budgets across all teams
• Budget strategy — Stars-and-scrubs vs balanced, position scarcity alerts (C, SS), nomination targets
• Bid guidance — For each nominated player: max bid, walk-away price, and alternative targets if you lose

Automated Monitoring (Cron Jobs)

Don't wait until you remember to check — set up scheduled agents to monitor your league on autopilot. Platforms like OpenClaw support cron-based agent execution, so the plugin checks your league on a schedule and alerts you when something needs attention.

Example schedules:

| Schedule | What it does | Cron | |---|---|---| | Lineup check | Flag injured starters, empty slots, bench players who should start | Daily at 8am | | Waiver wire scout | Monitor drops, cross-reference with roster needs and weak categories | Every 6 hours | | Weekly matchup prep | Scout opponent, identify swing categories, streaming targets, game plan | Monday 9am |

Example prompts for your scheduled agents:

• "Check my roster for injured players, empty slots, or anyone on the bench who should be starting. Flag any issues."
• "Check recent league activity for dropped players worth picking up. Cross-reference with my roster needs and weak categories. Only alert me if there's a clear upgrade."
• "Run a full weekly prep: scout my opponent, identify swing categories, check for streaming pitchers, and give me a game plan for the week."

This turns the plugin from reactive (you ask, it answers) to proactive (it watches your league and tells you when to act).

Cross-Session Memory

The plugin remembers your season across conversations:

| What it remembers | Why it matters | |---|---| | Matchup history | Win/loss record per opponent, category breakdowns by week | | Category trends | Which stats you're dominant/weak/improving in over time | | Roster moves | Every add, drop, and trade — avoids re-adding players you already tried | | Watchlist | Players you're tracking for future pickup | | Draft picks | Full auction history with bid amounts | | Preferences | Your punt strategy, draft approach, and other strategic decisions |

Memory is powered by a local SQLite database (~/.espn-fantasy/memory.db) with 14 MCP tools across 7 tables. At the start of each session, the agent loads your full context — matchup history, category trends, roster moves, and preferences — so it picks up where you left off.

How It Works

Two MCP servers working together:

ESPN Fantasy MCP (30 tools + 5 resources) — Connects to ESPN's API for live league data: rosters, standings, matchups, free agents, player stats, trades, draft board, scoring categories, probable pitchers, and transaction counts. Deployed on Railway via SSE or runs locally via stdio.

Memory MCP (14 tools) — Local SQLite server that persists matchup results, roster moves, category assessments, watchlist, draft picks, and user preferences across sessions. Runs locally via stdio.

8 Skills orchestrate both servers into complete workflows. When you ask "How's my matchup this week?", the matchup-scout skill calls get_standings → get_matchup → get_team_roster (opponent) → get_my_roster → loads memory for historical context → produces a category scoreboard with recommendations.

The 14 Scoring Categories

The league uses H2H Categories — you win individual stat categories each week, not total points. This shapes every recommendation:

| Hitting (7) | Pitching (7) | |---|---| | AVG | WHIP (lower wins) | | HR | ERA (lower wins) | | OPS | K (strikeouts) | | R (runs) | W (wins) | | RBI | L (lower wins) | | SB (stolen bases) | SV (saves) | | B_SO (lower wins) | HLD (holds) |

Built On

• cwendt94/espn-api — Python library for ESPN's Fantasy API (rosters, standings, matchups, player data). This repo is a fork with the MCP server, CLI, and plugin layered on top.
• kalil0321/reverse-api-engineer — Captures ESPN browser traffic to discover undocumented API endpoints beyond what espn-api covers. Used to map additional league data and build more powerful tooling.

---

Quick Start

Prerequisites

• Python 3.10+
• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
• ESPN Fantasy Baseball account

Setup

git clone https://github.com/garavitgabriel/espn-api.git
cd espn-api
uv sync

Authenticate

Option A — Browser login (easiest):

uv sync --extra browser              # first time only
uv run playwright install chromium   # first time only
uv run espn auth login

A browser opens, you log in to ESPN, and cookies are captured automatically.

Option B — Manual token:

Get your cookies from ESPN Fantasy > DevTools > Application > Cookies, then:

uv run espn auth token <ESPN_S2> <ESPN_SWID>

Option C — .env file:

cp .env.example .env   # edit with your values

Activate

| Platform | How | |---|---| | Claude Code | Open the project — auto-discovered via .claude-plugin/ | | Claude Desktop | Add to claude_desktop_config.json (see below) | | Claude Cowork | uv run espn build-plugin build --target claude --url <SSE_URL>, upload zip | | OpenClaw | ./install-openclaw.sh (see docs/openclaw-setup.md) |

<details> <summary>Claude Desktop config</summary>

{
  "mcpServers": {
    "espn-baseball": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/espn-api", "espn-mcp"]
    }
  }
}

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

</details>

---

Skills

Each skill orchestrates multiple MCP tools into a complete workflow:

| Skill | Triggers | What it does | |---|---|---| | matchup-scout | "matchup", "how am I doing", "opponent" | Category scoreboard, opponent scouting, press/protect/concede recommendations | | free-agent-finder | "free agent", "pickup", "waiver" | Position-filtered search ranked by category impact, pickup/drop verdicts | | trade-analyzer | "trade", "should I accept", "give X for Y" | Category-by-category impact table, net swing analysis, accept/decline verdict | | draft-assistant | "draft", "auction", "bid", "budget" | Live draft board tracking, bid guidance, budget pacing, position scarcity alerts | | weekly-prep | "weekly prep", "set my lineup", "Monday briefing" | Matchup preview, injury scan, start/sit, streaming targets, week plan | | category-strategist | "category analysis", "what should I punt" | Rate all 14 categories, identify punt targets, build path to 8+ wins | | waiver-wire-scout | "who got dropped", "league activity" | Monitor transactions, spot opportunities, avoid re-adding failed pickups | | season-outlook | "season outlook", "playoff chances" | Win/loss trajectory, category trends, playoff math, improvement plan |

CLI

uv run espn standings
uv run espn roster
uv run espn matchup --week 5
uv run espn free-agents --position SS --size 10
uv run espn player "Shohei Ohtani"
uv run espn compare "Shohei Ohtani" "Aaron Judge"
uv run espn trade --give "Player A" --receive "Player B"

# League info
uv run espn schedule --team "Gabriel"
uv run espn settings
uv run espn search "Ohtani"
uv run espn scoreboard --week 5

# Daily lineup decisions
uv run espn probable-pitchers                      # today's MLB starters with handedness
uv run espn sp-schedule "George Kirby"             # next scheduled start
uv run espn vs-team "Freddie Freeman" --opponent SEA  # BvP vs a specific team
uv run espn weekly-moves                           # add/drop count in the current period
uv run espn activity --team "Rolling Bunts" --period 4  # filter league activity

# Draft day
uv run espn scoring
uv run espn slots
uv run espn draft
uv run espn needs

# Auth
uv run espn auth login                        # browser login
uv run espn auth token <ESPN_S2> <ESPN_SWID>  # manual token
uv run espn auth status
uv run espn auth logout

# Plugin bundle
uv run espn build-plugin build --target openclaw
uv run espn build-plugin build --target claude --url https://your-app.up.railway.app/sse

uv run espn --help

MCP Tools (30)

<details> <summary>ESPN Fantasy MCP — live league data</summary>

| Tool | Description | |---|---| | get_my_roster | Your team's full roster with stats and injury status | | get_team_roster | Any team's roster by name | | get_matchup | Current or specific week matchup with H2H category breakdown | | get_standings | League standings sorted by rank | | get_free_agents | Best available players, filterable by position | | get_recent_activity | Recent adds, drops, and trades. Optional team_name and scoring_period filters | | get_box_scores | All matchup scores for a week | | get_player_info | Detailed stats for any player | | compare_players | Side-by-side player comparison | | get_league_rosters | Overview of all teams' rosters | | analyze_trade | Evaluate a trade by comparing give vs receive | | get_scoring_categories | League's H2H categories with direction | | get_roster_slots | Roster slot configuration | | get_draft_board | Draft picks, auction prices, team budgets | | get_roster_needs | Which positions you still need to fill | | get_schedule | Full season schedule with W/L results, live scores, current week | | get_league_settings | Comprehensive league config (playoffs, trades, FAAB, divisions, keepers) | | search_player | Fuzzy player search by partial name | | get_scoreboard | Lightweight matchup view with live scores and winners | | refresh_data | Pull latest data from ESPN | | get_player_news | Latest news, injury blurbs, and next game (via ESPN public API) | | get_player_splits | Splits vs LHP/RHP, home/away, by month, by count | | get_player_gamelog | Last 20 games with full stat lines | | get_mlb_games | MLB games with scores and status for a given date | | get_batter_vs_team | Batter's stats vs a specific team's pitchers (accepts explicit opponent_team) | | get_pro_schedule | Games-per-team over the next N days — for streaming decisions | | get_league_chat | League message board / trash talk