fantrax-mcp

MCP server for Fantrax fantasy baseball. It exposes tools to read league info, rosters, standings, free agents, and related data. The server is league-scoped: set one Fantrax league ID per deployment or local process.

Requirements

• Node.js 18+
• pnpm (or use npx / npm equivalents)

Environment

Variable	Required	Description
FANTRAX_LEAGUE_ID	Yes	Fantrax league ID (from the league URL)

The app does not load .env automatically for the stdio entrypoint; set variables in your shell or in your MCP client config (env).

MCP tools

All tools use the league configured by FANTRAX_LEAGUE_ID. Atomic tools map roughly one-to-one to Fantrax data; composite tools combine several calls for common workflows.

Atomic

Tool	Description
get_league_info	Full league info: teams, roster settings, player statuses. Prefer get_league_summary when you only need high-level details.
get_league_summary	Lightweight league info: name, season year, start/end dates, roster and draft settings.
get_standings	Standings: rank, points, and win percentage per team.
list_teams	All teams with teamId, teamName, and rank — use before tools that require a team ID.
get_all_rosters	Every team’s roster (player IDs, positions, salary). Prefer get_team_roster for a single team.
get_team_roster	One team’s roster (teamId).
get_free_agents	Free agents with name, MLB team, position, and eligible fantasy positions.
get_player_info	MLB player ADP-style data for ranking and valuation. Optional: position, limit, order.
get_scoring_categories	Stats that count in this league — use when comparing or recommending players.

Composite

Tool	Description
get_enriched_rosters	All rosters enriched with player names and ADP.
find_trade_targets	Trade targets by position and max ADP (teamId, position, maxAdp; optional status exclusions and whether to search all teams vs bottom half).
get_team_overview	One team’s roster, standings position, and league scoring categories (teamId).
get_waiver_candidates	Free agents ranked by ADP, with scoring categories — for add/drop decisions.
compare_players	Side-by-side comparison for two players by name, with league scoring context.

Run locally (stdio MCP)

Use this when your client spawns a subprocess and talks MCP over stdin/stdout (e.g. Cursor, Claude Desktop).

From the repo root:

pnpm install
export FANTRAX_LEAGUE_ID=your-league-id
pnpm mcp:stdio

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "fantrax": {
      "command": "pnpm",
      "args": ["mcp:stdio"],
      "cwd": "/absolute/path/to/fantrax-mcp",
      "env": {
        "FANTRAX_LEAGUE_ID": "your-league-id"
      }
    }
  }
}

Prefer the example above: it runs the lockfile-pinned tsx from this repo. Using npx tsx … for the local server works after pnpm install, but npx adds resolver/caching overhead on each spawn compared to pnpm mcp:stdio or pnpm exec tsx src/mcp-stdio.ts. If you use npm, npm run mcp:stdio with the same cwd is the analogous choice.

Important: Do not log to stdout in the stdio server; MCP uses stdout for the protocol.

Run remotely (HTTP MCP)

This repo is a Next.js app. The MCP endpoint is served by mcp-handler at:

https://<your-host>/api/mcp

Examples:

• Local dev: http://localhost:3000/api/mcp (after pnpm dev)
• Production: https://<project>.vercel.app/api/mcp (or your custom domain)

Clients that support Streamable HTTP can use the URL directly, for example:

{
  "mcpServers": {
    "fantrax-remote": {
      "url": "https://your-deployment.vercel.app/api/mcp"
    }
  }
}

If your client only supports stdio, proxy the remote server with mcp-remote:

{
  "mcpServers": {
    "fantrax-remote": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-deployment.vercel.app/api/mcp"]
    }
  }
}

Deploy to Vercel

1. Push this repository to GitHub (or another supported Git provider).
2. In the Vercel dashboard, import the project and select the Next.js preset.
3. Under Settings → Environment Variables, add FANTRAX_LEAGUE_ID for Production (and Preview if you want preview deployments to work).
4. Deploy. The build runs prebuild, which generates src/player-ids.json via scripts/generate-player-ids.ts.

Official reference: Deploying Next.js to Vercel.

Scheduled rebuilds

Production is redeployed automatically every Monday and Thursday at approximately 6:00 AM Eastern via .github/workflows/scheduled-rebuild.yml. The workflow POSTs to a Vercel Deploy Hook, which runs a full build (including prebuild player ID refresh).

One-time setup:

1. In Vercel: Settings → Git → Deploy Hooks — create a hook named e.g. scheduled-production-rebuild on branch main for Production.
2. In GitHub: Settings → Secrets and variables → Actions — add VERCEL_DEPLOY_HOOK_URL with the hook URL.

Manual trigger: Actions → Scheduled production rebuild → Run workflow.

Timezone note: GitHub cron uses UTC only (no DST). The schedule 0 11 * * 1,4 runs at 6:00 AM EST and 7:00 AM EDT. To target 6:00 AM during daylight saving instead, change the cron to 0 10 * * 1,4 (5:00 AM in winter).

Player data at build time

pnpm build runs prebuild first (package.json), which executes scripts/generate-player-ids.ts. That script fetches the MLB player ID catalogue from Fantrax’s public getPlayerIds API over HTTPS and writes src/player-ids.json. The build host must allow outbound network access; if the fetch fails, the build exits with an error. This step does not use FANTRAX_LEAGUE_ID (that variable is only for runtime MCP requests against your league).

Development

Script	Purpose
pnpm dev	Next.js dev server (remote MCP at /api/mcp)
pnpm mcp:stdio	Local stdio MCP server
pnpm build	Production build (prebuild regenerates player IDs)
pnpm test	Vitest
pnpm typecheck	tsc --noEmit