Fantasy Football Connector for Muse

Manage every fantasy team you own from one place. Sleeper, ESPN, and Yahoo. Rosters, matchups, standings, transactions, trade analysis, waiver targets, start/sit help, and weekly recaps, all inside Muse.

Built on patterns proven in BakaBois and the public Muse connector template.

What it does

Free, no login: connect any public Sleeper or ESPN league and read rosters, matchups, standings, and transactions. connect_league, list_my_teams, get_roster, get_matchup, get_standings, list_transactions.

Pro: trade analyzer, waiver targets, start/sit advice, plus private leagues (ESPN with your cookies, Yahoo with OAuth). Tools: analyze_trade, waiver_targets, start_sit_advice.

Commissioner: AI weekly recap for your league. Tool: weekly_recap.

The connector is read only. It cannot set lineups, claim players, or propose or accept trades.

Related MCP server: espn-ff-manager

Run it yourself

npm install
npm run typecheck
npm test
npm run build
npm start            # serves on PORT (default 8102)

POST-only MCP endpoint at /mcp. Health at /healthz. Docs at /muse.md, /llms.txt, /terms, /privacy.

Deploy anywhere Node runs. vercel.json and api/index.ts are included for Vercel; Dockerfile for containers.

Configuration

Copy .env.example to .env. Nothing is required to boot: every optional piece (Yahoo app, paid tiers, Stripe) degrades to an honest "not configured" instead of crashing.

Paid tiers

See PRICING.md. Enforcement is a 402 style gate inside each tool: the tool returns payment_required with payment_url and pricing_url, never a charge.

Stripe webhook setup (one-time, operator)

Paid tiers unlock automatically through the Stripe webhook at POST /v1/billing/webhook:

1. In the Stripe dashboard, create a webhook endpoint with URL https://<your-domain>/v1/billing/webhook (production: https://muse-fantasy-connector.vercel.app/v1/billing/webhook).

2. Subscribe it to checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed.

3. Copy the endpoint's signing secret into the STRIPE_WEBHOOK_SECRET env var (Vercel: project Settings → Environment Variables, Production) and redeploy.

How it works: the 402 payment_url appends the caller's Muse subject id as Stripe's client_reference_id; on checkout.session.completed the webhook verifies the Stripe signature, maps the amount to a tier, and stores the entitlement (Vercel KV in production, memory locally). customer.subscription.deleted revokes it. Test-mode events are logged but never grant tiers. Without the secret the endpoint answers 501 and tiers fall back to the PREMIUM_SUBJECTS / COMMISSIONER_SUBJECTS env lists. Billing event audit log (no PII without the admin token): GET /v1/billing/events with Authorization: Bearer <BILLING_ADMIN_SECRET>; config status: GET /v1/billing/status.

Privacy and terms

PRIVACY.md and the hosted /privacy page. Terms at /terms. League credentials arrive per request from Muse's Secure Credentials Store, are used once, and are never stored or logged; only paid-tier entitlements persist (see PRIVACY.md).

Repo layout

src/            MCP server, billing, tools, providers (sleeper/espn/yahoo)
api/index.ts    Vercel adapter
tests/          41 tests: billing, providers (fixtures), transport, gating
connectors/muse/  Muse directory submission pack
.claude-plugin/   Claude Code plugin manifest
skills/           Claude skill for fantasy management

Status

Tests: 41 passing. Live E2E verified 2026-09-27 against the real BakaBois ESPN league (1446375): connect, standings, transactions, and the 402 paywall all green.

Yahoo: OAuth 2.0 authorization code + PKCE is implemented and fixture tested. This matches Yahoo's current documented contract (verified 2026-09-27; Yahoo's docs now require OAuth 2.0, the old OAuth 1.0a is legacy). Live Yahoo needs an approved Yahoo app with a registered redirect URI; not yet verified end to end.

License

MIT. Not affiliated with Sleeper, ESPN, or Yahoo.