# Fantasy Baseball for Claude & Codex

[![npm](https://img.shields.io/npm/v/fantasy-baseball-mcp)](https://www.npmjs.com/package/fantasy-baseball-mcp)

Manage your **Yahoo Fantasy Baseball** team from Claude or Codex with built-in skills for
daily roster reviews, weekly post-mortems, automated lineup adjustments, and free-agent scouting.

All Yahoo league reads and writes run through a signed-in browser: **Claude in Chrome** or the
**Codex Browser plugin**. The supported workflow does not use the Yahoo Fantasy Sports API.

The MCP server remains useful for saving the browser-discovered default team and for deeper
player-performance analysis through the **MLB Stats API**, **Baseball Savant Statcast**, and
**FanGraphs**.

> [!WARNING]
> Yahoo has revoked Fantasy Sports API access for unverified developers. This project therefore
> uses a signed-in browser for all Yahoo league data and actions; the preserved Yahoo API code is
> not used in the supported workflow.

## Contents

- [Install](#install)
  - [Claude Desktop](#claude-desktop)
  - [Codex desktop app](#codex-desktop-app)
- [Connect your Yahoo team](#connect-your-yahoo-team)
- [Talk to your team](#talk-to-your-team)
- [Good to know](#good-to-know)
- [License](#license)

---

## Install

Pick the app you use — you only need one. Then continue to
[Connect your Yahoo team](#connect-your-yahoo-team).

### Claude Desktop

**1. Add the extension**

1. Download `fantasy-baseball-vX.X.X.mcpb` from the **[Releases page](../../releases/latest)**.
2. In Claude Desktop, go to **Settings → Extensions**.
3. Drag the file into the Extensions window and click **Install**.

**2. Add the Fantasy Baseball skill** (guided start/sit and roster-review workflow)

1. Download `fantasy-baseball-skill-vX.X.X.zip` from the **[Releases page](../../releases/latest)**.
2. Go to **Settings → Capabilities** and turn on **code execution**.
3. Go to **Customize → Skills**, click **+ → Create skill → Upload a skill**, and choose the ZIP.

### Codex desktop app

Requires **Node.js** ([nodejs.org/download](https://nodejs.org/en/download) — install the LTS
build). The plugin bundles the public analysis tools and the Fantasy Baseball skill in one step.

1. In the Codex app, go to **Settings → Plugins → Add plugin marketplace**.
2. Add from a GitHub repo:
   - **Source:** `dingyiyi0226/fantasy-baseball-mcp`
   - **Git ref:** `master`
   - **Sparse paths:** *(leave blank)*
3. Open the **Fantasy Baseball** marketplace and install the **Fantasy Baseball** plugin.
4. Continue to [Connect your Yahoo team](#connect-your-yahoo-team).

---

## Connect your Yahoo team

No Yahoo developer app, Client ID, Client Secret, or OAuth setup is needed.

### Codex

In a Codex chat, ask:

```text
Open https://baseball.fantasysports.yahoo.com in the in-app browser so I can sign in.
```

Sign in to Yahoo in that in-app browser. Keep the session there; all roster, matchup, player,
transaction, lineup, and add/drop workflows use it.

### Claude

Connect Claude in Chrome, open `https://baseball.fantasysports.yahoo.com`, and sign in to Yahoo in
that connected Chrome browser.

Then ask `show my Yahoo fantasy teams`. The skill discovers the visible leagues and teams from the
browser. If more than one team is available, choose one; the MCP server saves that
browser-discovered team as the local default.

If Yahoo is signed out later, the workflow stops and asks you to sign in in the same browser. It
does not fall back to OAuth or the Yahoo API.

---

## Talk to your team

| Say this... | To do this |
| --- | --- |
| `fantasy show roster` | Show your current roster |
| `fantasy my matchup` | Summarize this week's matchup |
| `fantasy standings` | Show league standings |
| `fantasy who should I add?` | Find free-agent targets |
| `who's pitching tomorrow?` | List probable starters; add “who's a free agent?” to check availability |
| `analyze Shohei Ohtani` | Compare recent performance with Statcast and FanGraphs indicators |
| `move <player> from BN to <slot>` | Makes one approved lineup swap in the signed-in Yahoo browser, then verifies it saved |
| `set my lineup today` | Applies the agreed start/bench moves from a roster review |
| `add <free agent>` | Adds that exact free agent when there is an open roster spot |
| `add <free agent> and drop <player>` | Submits only that exact approved add/drop pair and verifies the resulting roster |
| `review my roster today` | Reviews the current matchup, lineup, open slots, and free-agent or streamer opportunities |
| `who on my bench should I start tonight?` | Recommends exact start/bench swaps and explains why |
| `weekly review` | Grades lineup choices, adds/drops, and category strategy for this week or the week just finished |
| `can I still win this week?` | Identifies realistic category flips and the best remaining path |

Yahoo actions use the signed-in session in Codex's in-app browser or Claude's connected Chrome.
They stop if Yahoo is not signed in or the requested move is ambiguous. You can always ask for
advice first; an add/drop is submitted only after you explicitly approve the exact player or pair.

## Good to know

- The MCP server is still used for public player analysis and the locally saved default Yahoo team.
  Browser-only roster and matchup reads can work from the skill without Yahoo API credentials.
- The current browser owns the Yahoo login session. The local config stores only the
  browser-discovered default league/team identifiers for the supported workflow.
- Legacy Yahoo OAuth/API code remains in the package for possible future compatibility, but normal
  startup does not register or use it.
- **For batters, we use** season, 14-day, and 30-day splits; xBA, xSLG, xwOBA, and their
  expected-vs-actual gaps; exit velocity, hard-hit rate, barrel rate, launch angle, sweet-spot rate,
  and batted-ball distance; WAR, wRC+, wOBA, ISO, BABIP, K%, BB%, SwStr%, GB%, FB%, HR/FB, and LD%.
- **For pitchers, we use** season, 14-day, and 30-day splits; xBA, xSLG, and xwOBA allowed;
  exit velocity, hard-hit rate, barrel rate, and launch angle allowed; WAR, ERA, FIP, xFIP, WHIP,
  K%, BB%, SwStr%, GB%, FB%, HR/FB, BABIP, and LOB%.

## License

MIT