# yahoo-fantasy-mcp

[![CI](https://github.com/brettadams0/yahoo-fantasy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/brettadams0/yahoo-fantasy-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](package.json)

An MCP server over Yahoo Fantasy Sports, backed by a self-owned Yahoo Developer
OAuth2 app. Read-only — it reports on leagues, rosters, and matchups but does not
set lineups or make transactions.

Runs over stdio, registered in `~/.claude.json` as `yahoo-fantasy`.

## Tools

| Tool | Purpose |
|---|---|
| `yahoo_get_my_games` | Fantasy games (NFL, NBA, MLB, NHL) the account has played |
| `yahoo_get_my_leagues` | Leagues for the account, optionally filtered by game |
| `yahoo_get_league_settings` | Scoring rules, roster slots, league configuration |
| `yahoo_get_league_standings` | Current standings with W/L/T and points |
| `yahoo_get_league_transactions` | Adds, drops, and trades |
| `yahoo_get_scoreboard` | Matchups and scores for a given week |
| `yahoo_get_team_roster` | A team's roster, optionally for a specific week |
| `yahoo_get_team_matchups` | A team's full matchup history |
| `yahoo_search_league_players` | Player search within a league, with filters |
| `yahoo_fantasy_raw_get` | Escape hatch — arbitrary path against the Fantasy API |

`yahoo_fantasy_raw_get` exists because Yahoo's API surface is much wider than the
typed tools above, and its response shapes are too irregular to wrap exhaustively.
Use it when a typed tool doesn't cover what you need.

## Auth

OAuth2 with a refresh token in `credentials/token.json` (gitignored). Yahoo
**does** rotate refresh tokens on use, so the stored token is rewritten after each
refresh — meaning `credentials/` must be writable, and restoring an old backup of
it will fail with an invalid-grant error rather than working.

```bash
npm run authorize    # one-time browser consent
npm run check-auth   # verify the stored token still works
```

## Setup

Requires Node 20+.

1. Create an app at [developer.yahoo.com/apps](https://developer.yahoo.com/apps/)
   with **Fantasy Sports → Read** permission. Set the redirect URI to **OOB**
   (out-of-band): Yahoo displays the code on screen instead of redirecting, so
   there is no callback server to run.
2. Save the id and secret to `credentials/client_secret.json` — see
   `credentials/client_secret.example.json`. `credentials/` is git-ignored.
3. Authorize and register:

   ```bash
   npm ci
   npm run authorize
   claude mcp add yahoo-fantasy -- node <path>/yahoo-fantasy-mcp/src/index.js
   ```

## Tests

```bash
npm test
```

Registration plus the OAuth constants that silently break consent if changed —
notably the out-of-band redirect. No network and no credentials.

## Layout

```
src/auth.js            token load, rotate-on-refresh, caching
src/fantasy.js         all tool registrations
src/index.js           McpServer construction + stdio transport
scripts/authorize.js   one-time OAuth consent flow
scripts/check-token.js token health check
```

## Notes

- Yahoo's resource keys are positional and awkward: a league key looks like
  `nfl.l.123456`, a team key like `nfl.l.123456.t.7`. `yahoo_get_my_leagues` is
  the reliable way to discover the keys the other tools need.
- The API returns XML-shaped JSON with numeric-string object keys and `count`
  fields rather than plain arrays. Responses are passed through as-is, so expect
  that structure rather than idiomatic JSON.