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
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 Code
Claude Desktop
Cursor
Codex
Other clients
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
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
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:
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
Returns count, the number of teams that matched, and teams, each with id, alias, market and name.
find_games
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
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:
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
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
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:
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.
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.
Report bugs in GitHub issues.