cricket-mcp

A cricket stats nerd's dream, wired directly into Claude.

cricket-mcp is an MCP (Model Context Protocol) server that turns 10.9 million ball-by-ball deliveries from Cricsheet into a queryable cricket brain. Think ESPNcricinfo's Statsguru, but you just ask questions in plain English and get answers.

21,000+ matches. Every format. Every ball. All sitting in a local DuckDB database that answers in milliseconds.

What can it do?

Ask Claude things like:

• "How does Kohli bat against Hazlewood in ODIs?"

• "Best death bowlers in IPL by economy"

• "Kohli's average while chasing in ODIs"

• "Who is close to 10000 Test runs?"

• "What would Kohli average without Hazlewood?"

• "Does the toss matter in T20s?"

• "IPL 2024 standings and top performers"

• "Which bowlers have the best dot ball % at the death?"

• "Which batters are improving this season?"

• "Break down Rohit Sharma's record against each of England's bowlers"

• "Who had the biggest impact in the T20 World Cup 2024 final?"

• "Bumrah's last 10 T20 innings — is he in form?"

• "Fastest hundred in IPL history?"

• "Highest successful T20 chase ever?"

• "Is Kohli actually a big-match player?"

• "Has India ever lost a super over?"

• "Longest streak of 50+ scores in ODIs?"

• "How do Kohli and Rohit do batting together?"

Related MCP server: nfl-mcp

Tools (33 total)

Player Stats

Match & Team Queries

Records & Leaderboards

Venue & Partnerships

Drama & Big Matches

Batter vs Bowler Matchups

Phase & Situation Analysis

Team & Tournament

Career & Trends

Fielding & Dismissals

Impact Scoring

Innings Analysis

Every tool supports filters: format (Test/ODI/T20/IT20), gender, team, opposition, venue, city, season, tournament, and date range.

Setup

Prerequisites

• Node.js 18+

• Claude Desktop (or any MCP client)

Install

git clone https://github.com/mavaali/cricket-mcp.git
cd cricket-mcp
npm install

Ingest the data

This downloads all Cricsheet data (~94 MB ZIP, 21,000+ matches), loads it into a local DuckDB database, and enriches player metadata (batting/bowling styles) from the bundled CSV — one command, nothing else to run:

npm run ingest

Takes a few minutes. You'll see progress like:

Downloading from https://cricsheet.org/downloads/all_json.zip...
Download size: 93.7 MB
Extracted 21270 JSON files
Ingested 21270/21270 matches (10,895,339 deliveries)
Creating indexes...
=== Ingestion Complete ===
  Matches:    21270
  Deliveries: 10895339
  Players:    14406

Keep data up to date

Cricsheet publishes new matches daily. Instead of re-ingesting everything, pull just the recent matches:

npm run update          # last 7 days (default)
npm run update -- --days 2   # last 2 days
npm run update -- --days 30  # last 30 days

Downloads recently_played_N_json.zip from Cricsheet, skips matches already in the DB, inserts only new ones, and re-runs enrichment for any new players. Takes seconds.

Prefer it fully hands-off? Add --auto-update to the serve command and the server checks freshness at startup and pulls the right incremental feed itself (gaps larger than 30 days get a warning to re-ingest instead, since incremental feeds can't fill them without holes):

npx tsx src/index.ts serve --auto-update

Without the flag, the server logs a warning at startup when the data is noticeably stale (more than ~10 days behind — Cricsheet itself processes matches with roughly a week of lag).

For a full rebuild (e.g., to pick up Cricsheet corrections to historical data):

npm run ingest -- --force

Player metadata enrichment

Cricsheet data doesn't include player attributes like batting hand or bowling style. The repo bundles data/player_meta.csv (from the cricketdata R package, 16K players), and ingest/update apply it automatically — this is what powers get_style_matchup ("How does Kohli bat against left-arm pace?").

To re-run manually or use your own CSV:

npm run enrich                      # bundled CSV
npm run enrich -- --csv my.csv     # custom CSV

Pass --no-enrich to ingest/update to skip it.

Note: The MCP server must not be running during enrichment or updates (DuckDB allows only one write connection). Quit Claude Desktop first, run the command, then reopen.

Connect to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "cricket": {
      "command": "npx",
      "args": ["tsx", "/path/to/cricket-mcp/src/index.ts", "serve"]
    }
  }
}

Replace /path/to/cricket-mcp with the actual path. Restart Claude Desktop.

That's it. Start asking cricket questions.

Connect to VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "cricket-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/cricket-mcp/src/index.ts", "serve"]
    }
  }
}

The -y flag prevents npx from prompting for install confirmation, which would hang the MCP stdio transport.

OneLake backend (Microsoft Fabric)

Instead of a local DuckDB file, cricket-mcp can read Delta tables directly from a Fabric lakehouse via OneLake. All 33 tools work unchanged — DuckDB's delta and azure extensions handle the reads.

Prerequisites:

• Azure CLI installed and logged in (az login)

• A Fabric lakehouse with the cricket tables (players, matches, innings, deliveries) as Delta tables

• Workspace ID and Lakehouse ID from the Fabric portal

CLI usage:

npx tsx src/index.ts serve --backend onelake \
  --workspace-id <WORKSPACE_ID> \
  --lakehouse-id <LAKEHOUSE_ID>

VS Code mcp.json:

{
  "servers": {
    "cricket-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "tsx", "/path/to/cricket-mcp/src/index.ts",
        "serve", "--backend", "onelake",
        "--workspace-id", "${env:FABRIC_WORKSPACE_ID}",
        "--lakehouse-id", "${env:FABRIC_LAKEHOUSE_ID}"
      ],
      "env": {
        "FABRIC_WORKSPACE_ID": "<your-workspace-id>",
        "FABRIC_LAKEHOUSE_ID": "<your-lakehouse-id>"
      }
    }
  }
}

Note: The env block is important — VS Code may not inherit shell environment variables (e.g., from .zshrc) if launched from the Dock or Spotlight. Setting them explicitly in the config ensures they're always available.

How it works: On startup, cricket-mcp creates an in-memory DuckDB instance, loads the delta and azure extensions, authenticates via Azure CLI, and creates views over each Delta table in OneLake. The MCP transport connects immediately while the database initializes in the background — the first tool call waits for initialization to complete, subsequent calls resolve instantly.

See cricket-data-factory for the full pipeline that loads Cricsheet data into a Fabric lakehouse.

Remote hosting (HTTP transport)

By default, cricket-mcp uses stdio transport for local MCP clients (Claude Desktop, VS Code). To host the server remotely, use the HTTP transport:

npx tsx src/index.ts serve --transport http --port 3000

This starts an HTTP server on the specified port with a single /mcp endpoint. MCP clients connect by sending JSON-RPC requests to http://your-server:3000/mcp. The server supports multiple concurrent client sessions, each with its own session ID.

CORS headers are included on all responses, so browser-based MCP clients work out of the box.

Docker

Build a self-contained Docker image that ingests all Cricsheet data and serves over HTTP:

docker build -t cricket-mcp .
docker run -p 3000:3000 cricket-mcp

The build takes a few minutes (downloads ~94 MB of Cricsheet data, ingests 21K+ matches, enriches player metadata). The resulting image is ~600 MB.

To deploy on any cloud provider, push the image to a container registry and run it on a VM, managed container service (Cloud Run, ECS, Azure Container Apps), or Kubernetes.

Example Queries

"How does Kohli fare against Hazlewood in ODIs?"

Uses get_matchup with batter_name: "Kohli", bowler_name: "Hazlewood", match_type: "ODI".

"Best death bowlers in IPL"

Uses get_phase_stats with phase: "death", perspective: "bowling", event_name: "Indian Premier League", sort_by: "economy".

"Kohli's record while chasing in ODIs"

Uses get_situational_stats with situation: "chasing", player_name: "Kohli", match_type: "ODI".

"Who is close to 10000 ODI runs?"

Uses get_milestone_tracker with milestone_type: "runs", threshold: 10000, match_type: "ODI".

"What would Kohli average without Hazlewood?"

Uses get_what_if with player_name: "Kohli", perspective: "batting", exclude_bowler: "Hazlewood", match_type: "ODI".

"IPL 2024 standings and top performers"

Uses get_tournament_summary with event_name: "Indian Premier League", season: "2024".

"Does the toss matter in T20s?"

Uses get_toss_analysis with match_type: "T20".

"India vs Australia head to head in Tests"

Uses get_head_to_head with team1: "India", team2: "Australia", match_type: "Test".

"How does Kohli bat against left-arm pace?"

Uses get_style_matchup with player_name: "Kohli", perspective: "batting", grouping: "arm".

"Bumrah's record against left-handers"

Uses get_style_matchup with player_name: "Bumrah", perspective: "bowling".

"Who had the biggest impact in the T20 World Cup 2024 final?"

Uses get_match_impact with match_id: "1415755" (find the ID via search_matches first).

Returns phase-relative impact scores: Bumrah's 2/18 in 4 overs scores an economy_value of 17.63 because his 4.5 RPO in death overs was extraordinary against a match death-over average of 10+. Axar Patel tops the chart (136.82) with a 47(31) plus a death-over wicket.

"Which batters are improving in T20s this season?"

Uses get_emerging_players with perspective: "batting", match_type: "T20".

"Who has the best dot ball % at the death in IPL?"

Uses get_discipline_stats with perspective: "bowling", phase: "death", event_name: "Indian Premier League", sort_by: "dot_ball_pct".

"Fastest hundred in IPL history?"

Uses get_innings_records with record_type: "fastest_hundred", event_name: "Indian Premier League".

Returns Chris Gayle's 30-ball hundred (175* off 66 vs Pune Warriors, 2013) at the top.

"Highest successful T20 chase?"

Uses get_team_records with record_type: "highest_successful_chase", match_type: "T20".

"Is Kohli a big-match player?"

Uses get_clutch_performance with player_name: "Kohli", event_name: "Indian Premier League".

Returns league/knockout/finals splits plus a clutch delta — e.g. Kohli's IPL league average of ~41 drops to ~26 in knockouts (finals included).

"Has India ever lost a super over?"

Uses get_super_overs with team: "India" — lists each super-over match with per-team scores and the aggregate record.

"Longest streak of 50+ scores in ODIs?"

Uses get_streaks with streak_type: "fifty_plus", match_type: "ODI". Set run_threshold: 100 for consecutive hundreds, or streak_type: "team_wins" for team streaks.

"How do Kohli and Rohit do batting together?"

Uses get_partnerships with player_name: "Kohli", player2_name: "RG Sharma", aggregate: true — stands together, total runs, average stand, and 50+/100+ stand counts.

How it works

1. Data: Cricsheet provides free, open ball-by-ball data for every international and major domestic cricket match in JSON format.

2. Storage: The ingest command downloads, parses, and loads this into a local DuckDB database — a columnar analytics engine that eats aggregation queries for breakfast.

3. Server: The MCP server exposes 33 tools over stdio. Claude picks the right tool based on your question, passes the right filters, and returns the stats.

Database schema

Four tables in a star schema:

• players — 14K players with Cricsheet registry IDs (optionally enriched with batting style, bowling style, playing role, country)

• matches — 21K matches with metadata (teams, venue, outcome, tournament)

• innings — innings-level data (batting/bowling team, targets, declarations)

• deliveries — 10.9M rows, one per ball bowled (batter, bowler, runs, extras, wickets)

Cricket logic handled correctly

• Batting average = runs / dismissals (not innings)

• Balls faced excludes wides (standard convention)

• Bowler runs exclude byes and legbyes

• Legal deliveries exclude wides AND noballs

• Bowling wickets only count bowling dismissals (not run outs)

• Maidens computed at the over level

• Test innings — chasing means 4th innings, setting means 1st innings

Data Coverage & Limitations

All statistics are derived from Cricsheet ball-by-ball data. Cricsheet is an open-source project that provides detailed delivery-level records — but it doesn't cover the full history of cricket. Think of it as a high-resolution camera that was installed partway through the movie.

Coverage windows

Data is updated regularly and includes matches through early 2026 at time of writing.

What this means in practice

• Career stats for active or recent players (Smith, Kohli, Root, Bumrah, etc.) are comprehensive and reliable.

• Career stats for players who debuted before ~2002 will only reflect the tail end of their careers. Tendulkar's numbers here, for example, cover roughly his last 12 years, not all 24.

• All-time leaderboards are effectively "21st century leaderboards." They should not be compared to official ICC career records, which span the full history of the game.

• Venue and head-to-head records only reflect matches within the coverage window, not the full historical record at a ground or between two teams.

What's not limited

Within the coverage window, the data is ball-by-ball — every delivery, every run, every dismissal, every extra. Phase analysis, matchup breakdowns, strike rates, dot ball percentages, and other granular metrics are all derived from actual delivery data, not aggregated scorecards.

Changelog

v0.10.0

• One-command setup: ingest and update now run player-metadata enrichment automatically from the bundled CSV (--no-enrich to skip, --enrich-csv to override). The separate enrich step is no longer required; the command remains for manual/custom-CSV runs and now defaults to the bundled CSV.

• Freshness at serve time: the server checks how far behind the data is at startup. By default it warns when stale (>10 days, accounting for Cricsheet's ~1-week processing lag); with serve --auto-update it pulls the smallest Cricsheet incremental feed that covers the gap, then serves. Gaps beyond 30 days are never auto-filled (a partial feed would leave a silent hole) — the warning points to a full re-ingest instead. Runs inside the background init, so the MCP handshake stays instant.

• Dockerfile: index creation now actually runs in its own stage step (the previous file skipped it), and the redundant enrich step is gone.

v0.9.0

• Fan records & drama tools (28 → 33): 5 new tools

  • get_innings_records — single-performance leaderboards: highest scores, fastest 50s/100s by balls faced, most 6s/4s in an innings, best bowling figures, most expensive over, most runs off one over

  • get_team_records — highest/lowest totals (lowest = all-out only), biggest & narrowest wins by runs or wickets, highest successful chases, tied matches

  • get_clutch_performance — league vs knockout vs finals splits from event_stage, with a clutch delta

  • get_super_overs — super-over match history with per-team scores and aggregate W/L

  • get_streaks — gaps-and-islands streaks: consecutive 50+ scores (adjustable threshold), ducks, team wins/losses

• get_partnerships pair mode: player2_name narrows to a specific pair, aggregate: true returns career pair summaries

• Fixed get_career_impact (ambiguous column reference), get_emerging_players (invalid table alias in recent-season filter — the tool errored on every call), and get_tournament_summary (bind error on aspect: "summary")

• Fixed eval runner import crash; eval suite expanded to 75 checks covering all new tools

v0.8.0

• Phase-relative impact scoring: bowling economy is now scored per-phase against the match's average economy for that phase. Conceding 6 RPO in death overs (where 10+ is typical) earns far more credit than the same economy in middle overs. Batting gets a death-over SR bonus (1.3×) and powerplay aggression bonus (1.1×).

v0.7.0

• Player Impact Rating: 3 new tools (get_match_impact, get_career_impact, get_player_form) that compute context-weighted impact scores combining batting contribution, bowling wicket quality + economy, and fielding

• Impact scores account for: run contribution %, strike rate vs match average, entry difficulty, lost chase discount, wicket quality (set/star batters, top order, partnership breaks), economy vs match run rate, fielding dismissals, match importance (tournament stage + closeness)

• 25 → 28 tools

v0.6.0

• HTTP transport: --transport http --port 3000 starts an HTTP server for remote hosting with session management and CORS support

• Dockerfile: multi-stage build that ingests data and serves over HTTP — docker build && docker run to deploy

v0.5.0

• Consolidated matchup tools (27 → 25): get_matchup now handles specific matchups, batter-vs-team breakdowns, and matchup leaderboards in one tool

• Pre-computed bowling_style_broad and bowling_style_arm columns during enrichment — eliminates per-row CASE expressions at query time

• Simplified search_players to a players-only query (no more JOIN on 10.9M deliveries)

• Added composite indexes on deliveries for wicket and match queries

• Sharpened all 25 tool descriptions with question-led format and cross-references for better LLM tool routing

• Added data coverage documentation with format-specific date ranges

v0.4.0

• OneLake backend: read Delta tables directly from a Microsoft Fabric lakehouse via DuckDB's delta + azure extensions (--backend onelake)

• Lazy connection initialization: MCP transport connects immediately; database setup runs in the background. Fixes VS Code MCP client timeouts when OneLake extensions take time to load.

• VS Code .vscode/mcp.json configuration documented

v0.3.0

• Player enrichment pipeline: npm run enrich loads batting/bowling style metadata from bundled CSV (16K players from cricketdata R package)

• New get_style_matchup tool: query batting stats by bowling style (pace/spin, arm categories) or bowling stats by batting hand

• Schema migration for existing databases — new columns added automatically on startup

• Fixed BOWLING_WICKET_KINDS not interpolating in SQL template literals (affected all wicket-counting queries)

v0.2.0

• Consolidated similar tools (28 → 25): get_matchup replaces separate batter-vs-bowler / bowler-vs-batter tools, get_player_stats replaces separate batting / bowling stats tools

• Added 5 new tools: fielding stats, dismissal analysis, season stats, player comparison, innings progression

• Extracted shared constants (BOWLING_WICKET_KINDS, PHASE_OVERS) to reduce duplication

v0.1.0

• 23 tools covering player stats, matchups, records, phase/situational analysis, team form, tournaments, milestones, emerging players, what-if scenarios

• Incremental data updates (npm run update) using Cricsheet's recent match feeds

• Full ingest pipeline: download → parse → load into DuckDB

• 19 evals

Data source

All data comes from Cricsheet, which provides free, open cricket data. Massive thanks to them for making this possible.

License

MIT