StatsPlus MCP Server

An MCP server that exposes the StatsPlus API as tools for use with Claude and other MCP-compatible clients.

Prerequisites

• Node.js 18+

• A StatsPlus league account linked to a team

Installation

git clone https://github.com/joshuarichard/StatsPlus-MCP.git
cd StatsPlus-MCP
npm install
npm run build

Configuration

Getting your session cookie

The StatsPlus API requires an active browser session. To get your cookie:

1. Log into https://statsplus.net/<your-league-url> in your browser

2. Open DevTools (Cmd+Option+I on Mac, F12 on Windows/Linux)

3. Go to Application → Cookies → https://statsplus.net

4. Copy the sessionid and csrftoken values and combine them:

   sessionid=<value>;csrftoken=<value>

Adding to your MCP client

Add the following to your MCP client config (e.g. ~/.claude/mcp.json for Claude Code):

{
  "mcpServers": {
    "statsplus": {
      "command": "node",
      "args": ["/path/to/StatsPlus-MCP/dist/index.js"],
      "env": {
        "STATSPLUS_LEAGUE_URL": "<your-league-url>",
        "STATSPLUS_COOKIE": "sessionid=<sessionid>;csrftoken=<csrftoken>"
      }
    }
  }

Replace:

• /path/to/StatsPlus-MCP — the absolute path where you cloned this repo

• <your-league-url> — your league's URL slug (e.g. myleague, mlb2025)

• <sessionid> — the sessionid cookie value from your browser

• <csrftoken> — the csrftoken cookie value from your browser

Alternatively, with the Claude Code CLI:

claude mcp add statsplus \
  -e STATSPLUS_LEAGUE_URL=<your-league-url> \
  -e "STATSPLUS_COOKIE=sessionid=<sessionid>;csrftoken=<csrftoken>" \
  -- node /path/to/StatsPlus-MCP/dist/index.js

Available Tools

Split IDs: 1 = Overall, 2 = vs Left-handed, 3 = vs Right-handed

Usage tips

• Name-to-ID resolution: Use find_player(name) for quick name → ID lookups without downloading the full roster. For a full org's players, use get_players(org_id) which filters by Parent Team ID.

• Ratings workflow: The ratings export is an async job that takes 60–90 seconds. To avoid blocking mid-workflow, call start_ratings_job() first, do your other lookups while it processes, then call get_ratings(poll_url) to collect results:

  start_ratings_job()              → { poll_url: "..." }
  get_player_batting_stats(...)    ← runs concurrently
  get_contracts(team_id: ...)
  get_ratings(poll_url: "...")     → results ready, no extra wait

  Calling get_ratings() without a poll_url starts a new job and blocks until complete. Ratings columns include batting attributes (Cntct, Gap, Pow, Eye, Ks) with L/R splits, Pot* potential counterparts, and positional grades. Key encoding notes:

  • Star ratings are stored as stars × 2 — e.g. 3.5 stars = 7, 5 stars = 10

  • International complex players have a negative League value (e.g. -100)

  • Column names are not guaranteed to be stable across OOTP versions

• Preseason / empty responses: During preseason, all stat endpoints return HTTP 204 with no data for the upcoming year. Always pass year=<most recent completed season> to get data.

• Fielding: get_player_fielding_stats returns one row per player per position per split. A player who appeared at multiple positions will have multiple rows — one for each.

• Game history: runs0/hits0/errors0 are the home team; runs1/hits1/errors1 are the away team. winning_pitcher, losing_pitcher, starter0, and starter1 are numeric player IDs. save_pitcher is 0 when there is no save pitcher.

• Contracts: salary0 is the current season salary, salary1 is next season, and so on through salary14. Unpopulated years are 0. is_major and no_trade are 0/1 integers. contract_team_id is the MLB org that holds the contract (use this with the team_id filter). get_contract_extensions uses the same schema for deals already signed but not yet in effect.

• Splits: All stat endpoints that accept a split parameter use 1 = Overall, 2 = vs Left-handed, 3 = vs Right-handed. Omitting split returns all three rows per player/team.

Development

npm run build       # Compile TypeScript
npm test            # Run tests
npm run test:watch  # Run tests in watch mode
npm run lint        # Type-check without emitting

License

MIT