fantrax-mcp

An MCP server that lets Claude (or any MCP client) read your Fantrax fantasy hockey league and the NHL schedule, so you can ask things like:

• "How is my matchup going this week, category by category?"

• "Which free-agent centers would help my faceoffs and still get games this week?"

• "If I drop X for Y, how many extra starts do I actually get?"

• "Will I hit the goalie minimum this week?"

• "Show the standings by division." / "Who played last night, and was he in someone's lineup?"

It is read-only: it never makes roster moves, claims, trades or lineup changes. You stay in charge in Fantrax; the server just gives Claude accurate numbers to reason with.

Unofficial project. It uses the same internal web API the Fantrax site uses, with your own logged-in browser session. Fantrax can change that API at any time, so expect occasional breakage. Use it for your own league and in line with Fantrax's terms.

What it can do

Anywhere a tool takes team, you can pass me, a team name (or part of it), a Fantrax team id, or a short team code from TEAM_CODES (see below). Timeframes are PROJ_SEASON, YTD and LAST_SEASON. Every response includes fetched_at (UTC) and nhl_date (the US-Eastern game date). Bad input, such as an unknown team, comes back as {"error": "..."} with a readable message.

Related MCP server: Yahoo Fantasy MCP

Is it a fit for my league?

It was built for, and tested on, one league. Before you set it up, check these:

Making those settings configurable is on the to-do list; pull requests are welcome.

Requirements

• A Linux machine that stays on (a small VM, LXC container or Raspberry Pi is plenty)

• Python 3.11 or newer

• Your Fantrax account, logged in through a browser

• For Claude Desktop: Node.js (it runs the mcp-remote bridge via npx)

Quick start

1. Install

sudo apt install -y python3-venv git
sudo useradd -r -s /usr/sbin/nologin fantrax
sudo git clone https://github.com/RakkenRoli/fantrax-mcp.git /opt/fantrax-mcp
cd /opt/fantrax-mcp
sudo python3 -m venv .venv
sudo .venv/bin/pip install .

2. Configure

sudo mkdir -p /etc/fantrax-mcp
sudo cp .env.example /etc/fantrax-mcp/env
sudo nano /etc/fantrax-mcp/env

At minimum set:

• FANTRAX_LEAGUE_ID: the id in your league's URL, fantrax.com/fantasy/league/<this part>/...

• FANTRAX_TEAM_NAME: your team's name exactly as Fantrax shows it. Put it in quotes if it contains spaces. Or set FANTRAX_TEAM_ID instead (the teamId= value on your roster page).

• MCP_AUTH_TOKEN: a long random secret. Generate one with openssl rand -hex 32.

All settings are listed under Configuration below.

3. Give it your Fantrax login

Fantrax has no public API, so the server reuses your browser session:

1. Log in at fantrax.com with "Remember me" ticked.

2. Install the Cookie-Editor browser extension, open it on fantrax.com, and export the cookies as JSON.

3. Save the export as /etc/fantrax-mcp/fantrax_cookies.json.

sudo chown -R root:fantrax /etc/fantrax-mcp
sudo chmod 750 /etc/fantrax-mcp && sudo chmod 640 /etc/fantrax-mcp/*

Treat that file like a password: anyone who has it is logged in to your Fantrax account. Never commit it or paste it anywhere.

4. Run it as a service

sudo cp deploy/fantrax-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now fantrax-mcp
sudo journalctl -u fantrax-mcp -n 20 --no-pager

Check it from the same machine:

curl -s -H "Authorization: Bearer <your token>" http://127.0.0.1:8765/healthz

200 with "ok": true means it is logged in and the scoring categories match.

5. Put HTTPS in front of it

MCP clients should reach the server over HTTPS. Any reverse proxy works; Caddy is the simplest. deploy/Caddyfile.snippet is a starting point; keep flush_interval -1, because MCP streams responses. If you use Caddy's tls internal certificates, the machine running Claude must trust Caddy's root certificate (see Troubleshooting).

Add the hostname you use to MCP_ALLOWED_HOSTS, then restart the service.

6. Connect Claude Desktop

Merge deploy/claude_desktop_config.snippet.json into your Claude Desktop config and replace the URL and token:

{
  "mcpServers": {
    "fantrax": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://fantrax.example.lan/mcp",
               "--header", "Authorization:${FANTRAX_MCP_AUTH}"],
      "env": {
        "FANTRAX_MCP_AUTH": "Bearer <your token>",
        "NODE_EXTRA_CA_CERTS": "/path/to/caddy-root.crt"
      }
    }
  }
}

The token is passed through an environment variable because mcp-remote arguments must not contain spaces. Drop NODE_EXTRA_CA_CERTS if your certificate comes from a public CA.

Restart Claude Desktop and ask: "Use the fantrax tools: how is my matchup this week?"

Other MCP clients work the same way: point them at https://<your-host>/mcp and send Authorization: Bearer <token>.

Configuration

Settings are environment variables, read from /etc/fantrax-mcp/env by the service.

Keeping it running

• The Fantrax cookie expires after a few months, or when you log out of Fantrax in that browser. session_health shows the expiry date and warns three days ahead. To renew, export the cookies again and overwrite the file. The server picks up the new file on the next call, so no restart is needed.

• Optional: let the server keep the cookie fresh. Fantrax refreshes some cookies on its responses. With FANTRAX_COOKIE_WRITEBACK=1 the server merges those back into the cookie file (atomically, only cookies already in the file, never deletions), so a restart doesn't fall back to an older login. The service needs write access to the folder for that, which the default unit blocks on purpose:

  sudo systemctl edit fantrax-mcp     # add the two lines below
  #   [Service]
  #   ReadWritePaths=/etc/fantrax-mcp
  sudo chmod 770 /etc/fantrax-mcp && sudo chmod 660 /etc/fantrax-mcp/fantrax_cookies.json
  sudo systemctl restart fantrax-mcp

  If the server can't write, it logs one warning and carries on without write-back.

• When Fantrax rejects a refresh, get_league_rosters serves the last good copy of that timeframe (up to 48 h for projections and last season, 24 h for YTD) and lists it under stale; only if there is none does the part come back null under incomplete.

• Updating:

  cd /opt/fantrax-mcp && sudo git pull --ff-only && sudo .venv/bin/pip install -q . \
    && sudo systemctl restart fantrax-mcp

• Using it from scripts: /healthz returns 200 when the login works and the category map matches, 503 when not, 401 without the token. A good gate before any scheduled job:

  curl -fsS -H "Authorization: Bearer $MCP_AUTH_TOKEN" https://<host>/healthz >/dev/null \
    || { echo "Fantrax session unhealthy" >&2; exit 1; }

How the numbers are produced

• Matchup totals come from Fantrax's standings table, the same numbers Fantrax scores on. Live scoring is used only for Fantrax's own projection.

• Lineup simulations solve each day's lineup exactly (players with multiple positions included) against the real NHL schedule, so "usable starts" means games that fit in an active slot, not just games played by the NHL team.

• Goalie rates (GAA, SV%) are recomputed from goals against, shots against and minutes when goalies are combined. Averaging per-game rates gives the wrong answer.

• Fantrax does not project takeaways (Tk) or time on ice (TOI). In season projections these are reported as missing (null), not as zero.

Development

python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest -q tests

Tests never touch your real login: tests/conftest.py forces a dummy cookie file, even if your service environment is loaded in the shell. Several fixtures are real Fantrax responses from the author's league; if you change the category or team mappings for your league, a few of those tests will need their expectations updated.

fantrax_raw is the quickest way to inspect a response shape when Fantrax changes something. scripts/capture_standings_fixtures.py saves fresh standings fixtures.

Changes to tool output are recorded in CHANGELOG.md.

Troubleshooting

License

MIT, see LICENSE. Not affiliated with or endorsed by Fantrax or the NHL.