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)

Related MCP server: fpl-mcp

Environment

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

Composite

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