Skip to navigation

MCP server

Give Claude, Cursor or any MCP client read access to live games through @statpad/mcp.

@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.

When to use it

You wantUse
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 dataThe TypeScript SDK, or REST from any language
A coding agent that writes that app for youBuild with 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, 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 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 mcp add statpad -e STATPAD_API_KEY=sporty_... -- 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

VariableDefaultWhat it does
STATPAD_API_KEYRequiredYour 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_URLhttps://api.statpad.devThe API’s address. Point it at a local server, such as the replay in the blog. 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_LOGinfoThe 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

ToolWhat it returnsRequests
list_leaguesThe leagues your key can read1
find_teamsTeams in one league, with their ids1
find_gamesOne league’s games for a day, a range or right now1 to 3
get_gameOne game’s score and live situation1
get_box_scoreOne game’s player stat lines3
get_playsRecent plays, scoring plays, drives, or what changed since a seq2 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:

FieldWhen
truncatedtrue when the server trimmed the result to fit its size budget.
hintHow 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.”
noteContext for an empty or unusual result, such as no game in progress.
warningLess 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

ArgumentRequiredWhat it does
leagueYesA league alias, such as nfl.
queryNoA 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

ArgumentRequiredWhat it does
leagueYesA league alias.
dateOne of threeA schedule day in tz: YYYY-MM-DD, today, yesterday or tomorrow.
from and toOne of threeA range of start times as ISO 8601 datetimes with a zone, at most 31 days apart. from is inclusive and to exclusive.
liveOne of threetrue 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.
teamNoOnly one team’s games: a team id from find_teams, or a name such as Bills, which costs one more request.
tzNoThe IANA time zone for date and local_time. Defaults to America/New_York, the same as the API.

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

ArgumentRequiredWhat it does
leagueYesA league alias.
game_idYesA 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:

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

ArgumentRequiredWhat it does
leagueYesA league alias.
game_idYesA game id from find_games.
teamNoOnly one team: its id, abbreviation such as BUF, or name.
playerNoOnly players whose name contains this, such as allen, ignoring accents.
categoryNoOnly 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 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

ArgumentRequiredWhat it does
leagueYesA league alias.
game_idYesA game id from find_games.
modeNorecent, 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.
limitNoHow many plays or drives, newest last, from 1 to 50. Defaults to 10 recent plays, up to 50 scoring plays, and every drive.
after_seqNoOnly 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, 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:

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.

errorWhat happenedWhat to do
unauthorizedStatpad doesn’t accept the key.Copy a current key from the Keys page into STATPAD_API_KEY and restart the client.
forbiddenThe 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.
not_foundNo such game, team or player in that league.Use an id from find_games or find_teams for the same league.
rate_limitedThe account is sending requests too fast, perhaps from another app.Wait retry_after seconds.
quota_exhaustedThe account used this period’s allowance.Wait until resets_at, or upgrade the plan.
invalid_argumentThe 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, timeoutStatpad, the network or the server had a problem, or the call took more than 10 seconds.Try again in a few seconds.

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. 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 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.

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

Report bugs in GitHub issues.