yahoo-fantasy-mcp

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

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.

Related MCP server: ESPN Fantasy MCP Server

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.

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 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:

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

Tests

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.