> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# MCP server

> Set up @statpad/mcp, the Statpad MCP server for AI agents. Covers when to use it instead of the SDK, setup for Claude Code, Claude Desktop, Cursor and other clients, environment variables, every tool with its arguments and results, request costs, limits and versioning.

`@statpad/mcp` is an MCP server that lets an AI agent read Statpad. Connect it to Claude, Cursor or any MCP client, and the agent can look up schedules, live scores and game situations, play-by-play, drives and box scores for the leagues on your plan. Every result about one game carries the game's `seq`, so the agent can ask for only what changed since its last call.

It runs on your computer over stdio, needs Node.js 20 or newer, and only reads data. The source and its README are at [statpad-dev/statpad-mcp](https://github.com/statpad-dev/statpad-mcp).

## When to use it

| You want                                                                                   | Use                                                                  |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| An agent that answers questions about games, such as "What's the score of the Bills game?" | `@statpad/mcp`                                                       |
| An app, a backend or a script that reads or stores Statpad data                            | The [TypeScript SDK](/docs/sdk), or REST from any language           |
| A coding agent that writes that app for you                                                | [Build with AI](/docs/ai): the Statpad skill and the docs MCP server |

The MCP server is built on the SDK. It sends the same REST requests, then trims each answer to fit in a model's context. It doesn't use the WebSocket stream, so it can't push changes to the agent. The agent asks again, and passes the last `seq` to get only what's new.

## Get a key

Create a key for the MCP server on the **Keys** page at [app.statpad.dev](https://app.statpad.dev), instead of reusing one from an app. Every key on an account shares one request rate and one monthly allowance, so an agent that makes many calls slows your apps too. A key of its own shows its usage on the Keys page, and you can [revoke it](/docs/keys#revoke-a-key) without touching anything else.

## Set it up

Each client starts the server with `npx`, which downloads the package the first time. Replace `sporty_...` with your key.

#### Claude Code

```bash
claude mcp add statpad -e STATPAD_API_KEY=sporty_... -- npx -y @statpad/mcp
```

#### Claude Desktop

Open **Settings**, then **Developer**, then **Edit Config**, and add the server to `claude_desktop_config.json`:

**`claude_desktop_config.json`**

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "statpad": {
      "command": "npx",
      "args": ["-y", "@statpad/mcp"],
      "env": { "STATPAD_API_KEY": "sporty_..." }
    }
  }
}
```

Restart Claude Desktop after you save the file.

#### Cursor

Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` in one project:

**`~/.cursor/mcp.json`**

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "statpad": {
      "command": "npx",
      "args": ["-y", "@statpad/mcp"],
      "env": { "STATPAD_API_KEY": "sporty_..." }
    }
  }
}
```

Don't commit a project's `.cursor/mcp.json` with a key in it.

#### Codex

```bash
codex mcp add statpad --env STATPAD_API_KEY=sporty_... -- npx -y @statpad/mcp
```

#### Other clients

Any client that launches stdio servers works. The command is `npx -y @statpad/mcp`, and the server reads its key from the `STATPAD_API_KEY` environment variable. On Windows, a client that can't find `npx` may need the command `cmd` with the arguments `/c npx -y @statpad/mcp`.

The server checks the key's format when it starts. A key starts with `sporty_` and is 67 characters long. If `STATPAD_API_KEY` is missing or isn't shaped like a key, the server prints why and exits, and your client shows it as failed to start. Whether the key is current is for the API to say, on the first tool call.

Then ask in your own words, such as "Who has the ball in the Bills game?", "Who led the Vikings in receiving on Sunday?" or "What happened on the last drive?". The agent picks the tools.

### Environment variables

| Variable           | Default                   | What it does                                                                                                                                                                                                                                                                |
| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STATPAD_API_KEY`  | Required                  | Your API key. The server sends it only to the API, in the `Authorization` header, and never puts it in a tool result or a log line.                                                                                                                                         |
| `STATPAD_BASE_URL` | `https://api.statpad.dev` | The API's address. Point it at a local server, such as the [replay in the blog](https://statpad.dev/blog/claude-mcp-replay). The server sends its key to this address, so against a replay or a test server use a placeholder key shaped like a real one, as the blog does. |
| `STATPAD_MCP_LOG`  | `info`                    | The log level: `debug`, `info`, `warn`, `error` or `off`. Any other value logs at `info`, with a warning at startup.                                                                                                                                                        |

The server logs one JSON line per tool call to stderr, which your client shows in its MCP log. The line has the tool name, request count, duration and size, never the arguments or the data. `debug` adds a line for every request to Statpad, retries included, with its method, path, status, duration and request ID. The path holds the league and any game or team id, but never the query string.

## Tools

| Tool                              | What it returns                                                    | Requests |
| --------------------------------- | ------------------------------------------------------------------ | -------- |
| [`list_leagues`](#list_leagues)   | The leagues your key can read                                      | 1        |
| [`find_teams`](#find_teams)       | Teams in one league, with their ids                                | 1        |
| [`find_games`](#find_games)       | One league's games for a day, a range or right now                 | 1 to 3   |
| [`get_game`](#get_game)           | One game's score and live situation                                | 1        |
| [`get_box_score`](#get_box_score) | One game's player stat lines                                       | 3        |
| [`get_plays`](#get_plays)         | Recent plays, scoring plays, drives, or what changed since a `seq` | 2 or 3   |

Every tool is read-only. Results are JSON, both as text and as structured content that matches each tool's output schema, and fields with no value are left out. Every result can also carry these fields:

| Field       | When                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `truncated` | `true` when the server trimmed the result to fit its size budget.                                                              |
| `hint`      | How to get what a trimmed or partial result left out, such as "Pass team, or a shorter from and to range, to narrow the list." |
| `note`      | Context for an empty or unusual result, such as no game in progress.                                                           |
| `warning`   | Less than 5% of the account's monthly allowance is left. The server instructs the agent to tell you.                           |

The server also sends the agent instructions. They say to trust `list_leagues` for coverage, which data isn't available, how dates work, to quote `live_state.updated_at` as the time of a live situation, and not to poll in a tight loop.

### `list_leagues`

Takes no arguments. Returns `leagues`, each with `alias`, `name`, `sport` and `level`. Pass the `alias` as the `league` argument of the other tools. A league that isn't in this list isn't available to the key.

### `find_teams`

| Argument | Required | What it does                                                                                                                                                                                               |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `league` | Yes      | A league alias, such as `nfl`.                                                                                                                                                                             |
| `query`  | No       | A team name, market, abbreviation or both, such as `vikings`, `MIN` or `Buffalo Bills`, matched ignoring case and accents. Best matches come first. Without it, the tool lists every team, trimmed to fit. |

Returns `count`, the number of teams that matched, and `teams`, each with `id`, `alias`, `market` and `name`.

### `find_games`

| Argument        | Required     | What it does                                                                                                                                   |
| --------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `league`        | Yes          | A league alias.                                                                                                                                |
| `date`          | One of three | A schedule day in `tz`: `YYYY-MM-DD`, `today`, `yesterday` or `tomorrow`.                                                                      |
| `from` and `to` | One of three | A range of start times as ISO 8601 datetimes with a zone, at most 31 days apart. `from` is inclusive and `to` exclusive.                       |
| `live`          | One of three | `true` for the games in progress, at halftime or delayed. It reads yesterday and today in `tz`, so a game that runs past midnight still shows. |
| `team`          | No           | Only one team's games: a team id from `find_teams`, or a name such as `Bills`, which costs one more request.                                   |
| `tz`            | No           | The IANA time zone for `date` and `local_time`. Defaults to `America/New_York`, the same as the [API](/docs/pagination#dates-and-times).       |

Pass exactly one of `date`, `from` and `to` together, or `live`. A day or a range costs 1 request, `live` costs 2, and a team name adds 1.

Returns the day or days it read, `count`, and `games`, each with `id`, `status`, `scheduled_at` in UTC, `local_time` in `tz`, the `away` and `home` team names, `away_score`, `home_score`, `game_type`, `neutral_site` and `title`. A `time_tbd` game has no `local_time`. Statpad lists every game a league has published with both teams known, through the end of its season, so upcoming games are there too.

### `get_game`

| Argument  | Required | What it does                 |
| --------- | -------- | ---------------------------- |
| `league`  | Yes      | A league alias.              |
| `game_id` | Yes      | A game id from `find_games`. |

Returns the game's `status`, `scheduled_at`, teams, score and `venue`, its `live_state` and `seq`. `live_state` has the period, the clock as `M:SS`, the team in possession by name, the score, and the sport's block: down, distance, yard line and timeouts in football, the minute, stoppage time and red cards in soccer, timeouts and fouls in basketball, and shootout goals in hockey. `updated_at` is when Statpad last changed it. This is Bills at Vikings with 7:02 left, from the [sample game](/docs/replay):

**`get_game`**

```json title="get_game"
{
  "league": "nfl",
  "game_id": "01a1d60f-67be-7bdd-83f4-53286521d9bb",
  "status": "inprogress",
  "scheduled_at": "2026-11-10T01:15:00Z",
  "game_type": "regular",
  "neutral_site": false,
  "away": { "id": "01a1d60f-67be-7bdf-ac2f-bcdeeac1da68", "alias": "BUF", "name": "Buffalo Bills" },
  "home": { "id": "01a1d60f-67be-7bde-8a86-89128cd484ca", "alias": "MIN", "name": "Minnesota Vikings" },
  "away_score": 13,
  "home_score": 6,
  "venue": { "name": "U.S. Bank Stadium", "city": "Minneapolis", "state": "MN" },
  "live_state": {
    "period": 4,
    "clock": "7:02",
    "possession": "Buffalo Bills",
    "away_score": 13,
    "home_score": 6,
    "football": { "away_timeouts": 3, "down": 1, "home_timeouts": 2, "yardline": 95, "yards_to_go": 5 },
    "updated_at": "2026-11-13T17:58:25.937181Z"
  },
  "seq": 1101
}
```

`yardline` counts from the possessing team's own goal line, so 95 is the Minnesota 5. `updated_at` in the sample is when Statpad generated it. On the live API it's when the live state last changed.

`period_scores`, the score by period, appears once Statpad fills it.

### `get_box_score`

| Argument   | Required | What it does                                                                                                                               |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `league`   | Yes      | A league alias.                                                                                                                            |
| `game_id`  | Yes      | A game id from `find_games`.                                                                                                               |
| `team`     | No       | Only one team: its id, abbreviation such as `BUF`, or name.                                                                                |
| `player`   | No       | Only players whose name contains this, such as `allen`, ignoring accents.                                                                  |
| `category` | No       | Only one stat category, such as `passing`, `rushing`, `receiving`, `defensive`, `kicking`, `soccer`, `basketball`, `skaters` or `goalies`. |

Returns `lines`, the number of player lines that matched, and `categories`, a map from category to lines. Each line has `player`, `player_id`, the team's abbreviation, `jersey`, `position` when known, and `stats` with the [stat keys](/docs/coverage#stat-keys) for that category. Without a filter, a big game returns the top lines of each category, sets `truncated`, and says how to see the rest. It costs 3 requests: the game, its box score and its roster.

Box scores have player lines only, with no team totals. When the agent adds up player lines for a team total, the server's instructions tell it to say so.

### `get_plays`

| Argument    | Required | What it does                                                                                                                                                                                               |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `league`    | Yes      | A league alias.                                                                                                                                                                                            |
| `game_id`   | Yes      | A game id from `find_games`.                                                                                                                                                                               |
| `mode`      | No       | `recent`, the default, for the latest plays. `scoring` for scoring plays only. `drives` for drives, with team, result, plays, yards, first downs, points and time of possession. Only football has drives. |
| `limit`     | No       | How many plays or drives, newest last, from 1 to 50. Defaults to 10 recent plays, up to 50 scoring plays, and every drive.                                                                                 |
| `after_seq` | No       | Only what changed after this seq, from an earlier result. Works with `recent` and `scoring`.                                                                                                               |

Each play has `period`, `clock`, `team`, `type`, `description`, and the score after it. A scoring play also has `points`. The description names the players.

A call costs 2 requests, the game and its plays or drives. A game with more than 1,000 plays costs 3, and one with more than 2,000 can't be read to the end in one call, so the result says to follow it with `after_seq` instead.

#### Follow a game with `after_seq`

Pass the `seq` from a `get_game`, `get_box_score` or `get_plays` result for the same game as `after_seq`, and `get_plays` returns only the play changes since, with the newest `live_state` if it changed. It reads the game's [changes feed](/docs/streaming#without-the-stream), so a corrected play arrives again as a new version, with `op` and its `id`. A play Statpad removed arrives as `op: "delete"` with only its `id`.

With `mode: "scoring"`, it leaves out upserts of plays that aren't scoring plays. A play corrected to non-scoring, such as a touchdown overturned on review, doesn't appear, so this isn't a complete scoring ledger. Play deletions and `live_state` still come through. For the current scoring plays, call `get_plays` with `mode: "scoring"` and no `after_seq`.

This is `after_seq: 1101` with `limit: 2` on the sample game, at the touchdown from the [Quickstart](/docs/quickstart#follow-it-live):

**`get_plays (trimmed)`**

```json title="get_plays (trimmed)"
{
  "mode": "recent",
  "status": "inprogress",
  "after_seq": 1101,
  "head_seq": 1277,
  "caught_up": false,
  "plays": [
    {
      "op": "upsert",
      "id": "01a1d60f-a829-759c-a632-7e6eca90b7f0",
      "period": 4,
      "clock": "6:17",
      "team": "Buffalo Bills",
      "type": "rush",
      "description": "J.Cook up the middle for 5 yards, TOUCHDOWN.",
      "away_score": 19,
      "home_score": 6,
      "points": 6
    },
    {
      "op": "upsert",
      "id": "01a1d60f-a829-759c-a632-7e6eca90b7f0",
      "period": 4,
      "clock": "6:17",
      "team": "Buffalo Bills",
      "type": "rush",
      "description": "J.Cook up the middle for 5 yards, TOUCHDOWN. T.Bass extra point is GOOD, Center-R.Ferguson, Holder-T.Doman.",
      "away_score": 20,
      "home_score": 6,
      "points": 7
    }
  ],
  "live_state": { "period": 4, "clock": "6:17", "possession": "Buffalo Bills", "away_score": 20, "home_score": 6, "updated_at": "2026-11-13T17:58:32.808887Z" },
  "seq": 1112,
  "hint": "More changes follow. Call again with after_seq 1112."
}
```

Both plays have the same `id`: the second is the correction that adds the extra point. `seq` is the last change the call read, so the next call with `after_seq: 1112` continues right after it and skips nothing. `caught_up` turns `true` when `seq` reaches `head_seq`, the newest change in the game.

If the changes feed no longer holds `after_seq`, the result has `resync_required: true`, a fresh read of the game's live state, and a new `seq` to continue from.

## Errors

A failed call returns a tool error, with `isError` set and a JSON body the agent reads. `error` is a code and `message` says what to do. When the API answered, the body also has `detail` and `request_id`, plus `retry_after`, `resets_at` or `min_seq` when they apply.

| `error`                              | What happened                                                                            | What to do                                                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `unauthorized`                       | Statpad doesn't accept the key.                                                          | Copy a current key from the Keys page into `STATPAD_API_KEY` and restart the client.                       |
| `forbidden`                          | The key can't read that league, or the account has no active access.                     | `list_leagues` shows what the key can read. Check your plan at [app.statpad.dev](https://app.statpad.dev). |
| `not_found`                          | No such game, team or player in that league.                                             | Use an id from `find_games` or `find_teams` for the same league.                                           |
| `rate_limited`                       | The account is sending requests too fast, perhaps from another app.                      | Wait `retry_after` seconds.                                                                                |
| `quota_exhausted`                    | The account used this period's allowance.                                                | Wait until `resets_at`, or upgrade the plan.                                                               |
| `invalid_argument`                   | The arguments can't be served, such as a team name that matches more than one team.      | The message lists the candidates or what to change.                                                        |
| `internal`, `unavailable`, `timeout` | Statpad, the network or the server had a problem, or the call took more than 10 seconds. | Try again in a few seconds.                                                                                |

[Errors](/docs/errors) describes the API's codes in full.

## Plans and limits

The MCP server reads over REST only, so it works on every plan, Developer included. It uses the same request rate and monthly allowance as the rest of your account, per [Rate limits](/docs/get-started/rate-limits). On Developer, that's 1 request a second with a burst of 10, and 25,000 requests a period.

The server keeps each call small, so an agent can't run up your usage by accident:

* A tool call makes at most 3 reads of the API, shown in the [Tools](#tools) table, and gives up after 10 seconds.
* It retries a failed read once, and never retries `quota_exhausted`. So one call sends at most 6 HTTP requests.
* A result aims for about 2,000 tokens and never goes past about 6,000. When it trims a list, it says so and tells the agent how to narrow it.
* When less than 5% of the monthly allowance is left, every result carries a `warning`.

Each read counts against your allowance like any other request: a `2xx` or `304` counts once, and HTTP error responses don't count. So a call usually costs at most 3 requests from your allowance. When a network failure loses a response that Statpad already sent, that request has counted, and the retry counts again. An agent following a game with `get_plays` and `after_seq` every 30 seconds uses about 240 requests an hour.

## What isn't available yet

The server's instructions list what Statpad doesn't serve through these tools, so the agent says so instead of guessing:

* standings
* injuries and transactions
* team rosters and depth charts
* betting odds
* season stats and league leaders
* player profiles and player search
* team totals and score by period in box scores

Statpad started collecting each league in November 2026, so earlier games aren't there.

## Privacy

The server runs on your computer. Your key stays in your MCP client's configuration and the server's environment, and the server sends it only to the API at `STATPAD_BASE_URL`, which is `api.statpad.dev` unless you change it. The agent's questions and the data it reads go to whichever model your client uses, under that client's terms.

## Versioning

The server follows semantic versioning. Until 1.0, a minor release can change tool names, arguments and results. `npx -y @statpad/mcp` runs the latest release, so pin an exact version if you need a fixed one. A range such as `@0.1` still moves to new patch releases.

```bash
claude mcp add statpad -e STATPAD_API_KEY=sporty_... -- npx -y @statpad/mcp@0.1.3
```

Report bugs in [GitHub issues](https://github.com/statpad-dev/statpad-mcp/issues).