Build with StatpadMCP serverNFL
Ask Claude about an NFL game while it replays on your laptop
A small Node server replays the recorded Bills at Vikings game on localhost. Point @statpad/mcp at it, ask Claude who has the ball, then move the game forward and watch the answer change when replay overturns a fumble.
With 6:00 left in the second quarter of Bills at Vikings on November 9, 2026, Josh Allen was sacked at his own 2 and lost the ball. Statpad published the play at seq 506 of the game's change journal:
(Shotgun) J.Allen sacked at BUF 2 for -8 yards (A.Van Ginkel). FUMBLES (A.Van Ginkel) [A.Van Ginkel], RECOVERED by MIN-A.Van Ginkel at BUF 1.
At seq 507 the live state said Minnesota had the ball at the Buffalo 1. At seq 520 the same play id came back as version 2, with one more sentence: "The Replay Official reviewed the passer was not down by contact ruling, and the play was REVERSED." By seq 523 Buffalo had the ball again, 4th and 23 at its own 2.
An agent that answers questions about games in progress has to get both of those answers right, at the moment you ask. In this post you'll connect Claude to a replay of that game and ask it yourself. You don't need an API key or a live game. A small Node server plays the recorded game back on your computer, and one environment variable points @statpad/mcp at it instead of at the Statpad API.
You won't write code this time. You'll run the server, connect your MCP client and move the game to the seqs where things happen.
What you need
- Node.js 20.12 or later. Run
node --versionto check. - An MCP client. The steps use Claude Code. Claude Desktop and Cursor work too, and their settings are below.
- The code. Download claude-mcp-replay.zip, unzip it and run
npm installin the folder. It installs@statpad/mcp0.1.0 and the MCP client that the tests andtool.mjsuse. The server itself needs no packages.
How the replay works
Statpad publishes the whole journal of this game at statpad.dev/samples/nfl-bills-at-vikings/changes.ndjson. It holds 1,277 changes, one per line, in seq order. Each change carries one entity, such as a play, the live state, a drive or one player's stat line, with its type, id and version. That's what the stream sends a client that resumes from seq 0.
To know what the game looked like at any seq, keep the newest version of every entity up to that seq. This is the function in replay.mjs that does it:
// The game as it stood at seq: the newest version of every entity, from the journal alone.
export function stateAt({ changes }, seq) {
const latest = new Map();
for (const change of changes) {
if (change.seq > seq) break;
latest.set(`${change.entity_type}:${change.entity_id}`, change);
}
const all = (type) =>
[...latest.values()]
.filter((change) => change.entity_type === type && change.op === 'upsert')
.map((change) => change.payload);
const one = (type) => all(type)[0] ?? null;
const bySequence = (a, b) => a.sequence - b.sequence;
return {
game: one('game'),
liveState: one('live_state'),
plays: all('play').sort(bySequence),
drives: all('play_group').sort(bySequence),
stats: all('player_game_stats'),
roster: all('game_roster'),
};
}The server answers the same paths as the Statpad API, such as /v1/nfl/games/{id} and /v1/nfl/games/{id}/plays, from that state. The other sample files on the sample responses page are real API responses for this game, so they're a check on the replay. npm test rebuilds the state at the last seq and compares it with them. The game, all 187 plays, the 25 drives, the 68 box score lines and the roster come out with the same data as game.json, plays.json, play-groups.json, boxscore.json and roster.json. At seq 1101 the live state matches game-live.json, the snapshot taken with 7:02 left in the fourth quarter.
✔ the journal alone rebuilds every sample file at the final seq (21.232329ms)
✔ seq 1101 matches the game-live sample (0.714822ms)
✔ at seq 507 Minnesota has the ball at the Buffalo 1 (36.709529ms)
✔ at seq 523 the same play comes back reversed, and Buffalo has the ball (8.876536ms)
✔ the game is listed as live only while it is in progress (22.872003ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 336.221918The last three tests run the real @statpad/mcp server in the test process and call its tools, with every request it makes answered by the replay. They check the two answers from the start of this post.
Start the replay
Start the server at seq 507, one change after the fumble:
node replay.mjs --at=507Replaying Bills at Vikings on http://localhost:8787, paused at seq 507 of 1277.
Connect Claude Code:
claude mcp add statpad-replay -e STATPAD_BASE_URL=http://localhost:8787 -e STATPAD_API_KEY=sporty_replayreplay0000.notarealkeyreplayserverignoresit00000000000 -- npx -y @statpad/mcp@0.1.0
Type a seq and press Enter to jump there, +N to move N changes, p to play or pause.The game stays at seq 507 until you move it. Leave this terminal open.
Connect Claude
Open a second terminal and run the claude mcp add line that the server printed. It adds an MCP server called statpad-replay to Claude Code. Claude Code starts @statpad/mcp with two environment variables:
STATPAD_BASE_URLsends its requests to the replay athttp://localhost:8787instead of to the Statpad API.STATPAD_API_KEYholds a placeholder.@statpad/mcpchecks that a key has the right shape before it starts, so it needs one. The replay ignores it, and it isn't a real key.
For Claude Desktop, open Settings, then Developer, then Edit Config. For Cursor, edit ~/.cursor/mcp.json. Both take the same entry:
{
"mcpServers": {
"statpad-replay": {
"command": "npx",
"args": ["-y", "@statpad/mcp@0.1.0"],
"env": {
"STATPAD_BASE_URL": "http://localhost:8787",
"STATPAD_API_KEY": "sporty_replayreplay0000.notarealkeyreplayserverignoresit00000000000"
}
}
}
}Restart Claude Desktop after you save the file.
Ask who has the ball
Start Claude Code with claude and ask:
Who has the ball in the Bills game right now?
Claude picks the tools itself. It usually starts with find_games and live: true, which asks for yesterday's and today's NFL games and keeps the ones in progress. Then it calls get_game for the situation. The replay's terminal prints each request @statpad/mcp sends:
GET /v1/nfl/games?tz=America%2FNew_York&limit=500&date=2026-11-15 -> 200
GET /v1/nfl/games?tz=America%2FNew_York&limit=500&date=2026-11-16 -> 200
GET /v1/nfl/games/01a1d60f-67be-7bdd-83f4-53286521d9bb -> 200The dates are the day you run it, not November 9. While the replayed game is in progress, the server lists it on every day, the way a live game shows up today. That's the only part of the replay that isn't in the recording.
This is the live state get_game returned to the model at seq 507:
{
"live_state": {
"period": 2,
"clock": "5:53",
"possession": "Minnesota Vikings",
"away_score": 3,
"home_score": 0,
"football": {
"down": 1,
"yardline": 99,
"yards_to_go": 1,
"away_timeouts": 3,
"home_timeouts": 3
},
"updated_at": "2026-11-13T17:58:19.44776Z"
},
"seq": 507
}yardline counts from the possession team's own goal line, so 99 is the Buffalo 1. Claude should tell you that Minnesota has 1st and goal at the 1 after recovering a Josh Allen fumble, with Buffalo up 3–0 and 5:53 left in the second quarter. The wording depends on your model. The JSON above is what it reads, and you can print it yourself with tool.mjs, shown below.
updated_at is November 13 because that's when the sample was generated. On the live API it's when Statpad last changed the live state, and the server's instructions tell the model to quote it as the time of the data.
Move the game forward
Go back to the replay's terminal, type 523 and press Enter. The server prints the plays between 507 and 523 as they're released:
#513 Q2 6:45 BUF 3, MIN 0 (Shotgun) J.Allen pass short left to D.Moore to BUF 10 for no gain (B.Murphy; T.Ingram-Dawkins). (version 2)
#515 Q2 5:53 BUF 3, MIN 0 Official Timeout at 05:53.
#520 Q2 6:00 BUF 3, MIN 0 (Shotgun) J.Allen sacked at BUF 2 for -8 yards (A.Van Ginkel). FUMBLES (A.Van Ginkel) [A.Van Ginkel], RECOVERED by MIN-A.Van Ginkel at BUF 1.The Replay Official reviewed the passer was not down by contact ruling, and the play was REVERSED.(Shotgun) J.Allen sacked at BUF 2 for -8 yards (A.Van Ginkel). (version 2)
at seq 523 of 1277Two of the three are new versions of plays the game already had. Seq 513 adds a second tackler to the play before the sack. Seq 520 is the reversal.
Now ask Claude in the same conversation:
Has anything changed since you last checked?
Every @statpad/mcp result has a seq, and the tool descriptions tell the model to pass it back to get_plays as after_seq to get only what changed since. When Claude does that, the replay answers with changes 508 to 523, and get_plays turns them into this:
{
"after_seq": 507,
"head_seq": 523,
"caught_up": true,
"plays": [
{
"op": "upsert",
"id": "01a1d60f-73fb-70b6-924e-720e4f665903",
"clock": "6:45",
"team": "Buffalo Bills",
"description": "(Shotgun) J.Allen pass short left to D.Moore to BUF 10 for no gain (B.Murphy; T.Ingram-Dawkins)."
},
{
"op": "upsert",
"id": "01a1d60f-746b-7e99-9dbe-4e559342de5a",
"clock": "5:53",
"team": "Minnesota Vikings",
"description": "Official Timeout at 05:53."
},
{
"op": "upsert",
"id": "01a1d60f-7437-7d24-b979-9380e6e37398",
"clock": "6:00",
"team": "Buffalo Bills",
"description": "(Shotgun) J.Allen sacked at BUF 2 for -8 yards (A.Van Ginkel). FUMBLES (A.Van Ginkel) [A.Van Ginkel], RECOVERED by MIN-A.Van Ginkel at BUF 1.The Replay Official reviewed the passer was not down by contact ruling, and the play was REVERSED.(Shotgun) J.Allen sacked at BUF 2 for -8 yards (A.Van Ginkel)."
}
],
"live_state": {
"clock": "5:58",
"possession": "Buffalo Bills",
"football": { "down": 4, "yardline": 2, "yards_to_go": 23 }
},
"seq": 523
}The fumble comes back with the same id and the review appended to its description. The live state has Buffalo with 4th and 23 at its own 2, and caught_up says there's nothing newer. Claude should tell you the fumble was overturned and that Buffalo kept the ball. If it calls get_game instead of get_plays, it still sees Buffalo with the ball, because every read returns the newest version of the game.
The order matters too. The play's text changed at seq 520, but the live state gave Minnesota the ball until seq 523. A model that read the play and the game separately in that window could see a reversed fumble and a live state that still gave Minnesota the ball. get_plays with after_seq returns both in one result, the plays and the newest live state, so the model reads them together.
See what the agent sees
tool.mjs calls one @statpad/mcp tool against the running replay and prints the result, without a model in between. It's the quickest way to check what your agent was given when an answer looks wrong:
node tool.mjs get_plays '{"league":"nfl","game_id":"01a1d60f-67be-7bdd-83f4-53286521d9bb","after_seq":507}'It starts @statpad/mcp the same way your client does, with the same two environment variables, so the result is the one Claude read.
More moments to try
Type a seq in the replay's terminal, then ask Claude about the game.
199. At seq 191 Carson Wentz threw an incomplete pass to Justin Jefferson with 5:30 left in the first quarter. Buffalo challenged, and at seq 199 the same play became "C.Wentz FUMBLES (Aborted) at MIN 43, RECOVERED by BUF-G.Rousseau". Ask at 191 and again at 199 who has the ball.1105. The Bills scored their last touchdown with 6:17 left. The game row moved to 19–6 at seq 1104, but the touchdown play arrived at 1106. At 1105get_gamereturns 19–6 as the game's score and 13–6 in the live state. Ask for the score and see which one your model reports.1111. The same touchdown comes back as version 2 with "T.Bass extra point is GOOD" added, and the score is 20–6.p. Plays the game from where it is at 4 changes a second, about five minutes for the whole game. Start at--at=0with--speed=2and ask Claude every few minutes how the game is going.
What the recording doesn't fix
The box score didn't follow the reversal. In this recording Josh Allen's stat line shows a lost fumble from seq 502 to the final, and Andrew Van Ginkel's shows a recovery. The play was reversed at 520, but the box score is a separate record and never caught up before the recording ended. If you ask Claude how many fumbles Allen lost, it will say one, because that's what get_box_score returns.
That matters for anything that scores players, like a fantasy app. In this game the play changed and the stat line didn't. Statpad can correct stats after a game is final, so an app that scores players should keep reading the box score after the game ends, and an agent that answers stat questions should say which record it used.
Switch to live data
To ask about real games, swap the replay for the live API. Create a key on the Keys page of your Statpad account. Make a new key for the MCP server 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 a lot of calls slows your apps down too.
claude mcp remove statpad-replay
claude mcp add statpad -e STATPAD_API_KEY=sporty_... -- npx -y @statpad/mcpThe Pro trial lasts 7 days and needs a card. When it ends it becomes Pro at $49 a month unless you cancel or pick another plan. The smallest plan, Developer, is $19 a month. Each tool call sends at most 3 requests, and every one counts against your plan.
Statpad covers the NFL, NBA, NHL, NCAA football and men's basketball, the Premier League, LaLiga, Bundesliga, Serie A and Ligue 1. The schedule lists every game the league has published with both teams known, through the end of its season, so you can ask about one before it starts. Chiefs at Bills is on Thanksgiving night, Thursday, November 26.
Run it
npm install
npm test
node replay.mjs --at=507Then run the claude mcp add line the server prints, start claude and ask who has the ball. Type 523 in the replay's terminal and ask again.
Limits
- The replay serves one recorded game in one league.
list_leaguesreturns only the NFL, and any other league answers403. - It has no WebSocket stream, rate limit headers or request allowance, and it ignores the key.
- Ids and
updated_attimes come from the sample, which was generated on November 13, 2026, so they don't match production. - The answers in this post are the tool results. Claude's wording, and which tools it calls, depend on the model and the client.
More from Build with Statpad
- Test that your live client gets a real game rightA six-test node:test file sends all 1,277 changes of a recorded NFL game through your change handler and checks what your app would show at the moments that break live clients.
- A shot map of Manchester United 4–4 Aston Villa in 125 lines of TypeScriptEvery shot in Statpad's Premier League play-by-play has pitch coordinates. This script turns one 8-goal draw into an SVG shot map and a score timeline, and covers the two coordinate traps.
- A live NFL scoreboard in SwiftUI, and the small server that holds the keyA Node server on @statpad/sdk holds the Statpad key and one stream subscription, and a SwiftUI app resumes from it by seq, tested against a recorded Bills at Vikings game.
- A fantasy football scoreboard for your Discord channelA first project with the Statpad API. One small Node script scores a fantasy matchup from NFL box scores and keeps a single Discord message up to date through a channel webhook.