loading…
Search for a command to run...
loading…
An MCP server that enables natural language querying of over 10 million ball-by-ball cricket deliveries stored in a local DuckDB database. It provides 26 tools
An MCP server that enables natural language querying of over 10 million ball-by-ball cricket deliveries stored in a local DuckDB database. It provides 26 tools for analyzing player matchups, situational stats, and historical records across all major cricket formats and tournaments.
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.
Ask Claude things like:
| Tool | What it does |
|---|---|
search_players |
Fuzzy name search with career summary |
get_player_stats |
Full batting or bowling stats (use perspective param) — avg, SR, 100s, 50s, HS, 4s, 6s, maidens, 5wi, best figures |
| Tool | What it does |
|---|---|
search_matches |
Find matches with filters + pagination |
get_head_to_head |
Team vs team W/L/D/T record |
get_match_scorecard |
Complete batting + bowling card for any match |
| Tool | What it does |
|---|---|
get_batting_records |
Rank players by runs, avg, SR, 100s, 50s, 6s, 4s, HS |
get_bowling_records |
Rank players by wickets, avg, econ, SR, 5wi |
| Tool | What it does |
|---|---|
get_venue_stats |
Ground stats — avg scores, bat-first win %, highest/lowest totals |
get_partnerships |
Highest batting partnerships |
| Tool | What it does |
|---|---|
get_matchup |
Head-to-head stats (both names), batter vs team bowling (batter + opposition), or matchup leaderboards (one name + record_type) |
get_style_matchup |
Batter vs bowling styles (pace/spin, left-arm/right-arm) or bowler vs batting hand |
| Tool | What it does |
|---|---|
get_phase_stats |
Batting/bowling stats by phase — powerplay (1-6), middle (7-15), death (16-20) |
get_situational_stats |
Stats while chasing, setting, under pressure, or by batting position. Format-aware (Tests use 4th innings for chasing) |
get_toss_analysis |
Toss impact on outcomes — bat first vs chase win %, by venue/team/format |
get_discipline_stats |
The boring stats that win tournaments — dot ball %, wide rate, boundary % |
| Tool | What it does |
|---|---|
get_team_form |
Recent form — last N results, win streak, avg scores, run rate |
get_tournament_summary |
Standings, top batters, top bowlers for any tournament/season |
| Tool | What it does |
|---|---|
get_milestone_tracker |
Players near career milestones (10000 runs, 500 wickets, etc.) |
get_emerging_players |
Players whose recent stats significantly outperform career baseline |
get_what_if |
Counterfactual — recalculate career stats excluding opponents, bowlers, venues, or tournaments |
get_season_stats |
Year-by-year career breakdown |
get_player_comparison |
Side-by-side comparison of two players |
| Tool | What it does |
|---|---|
get_fielding_stats |
Catches, stumpings, run outs per fielder |
get_dismissal_analysis |
Breakdown of how a player gets out (or gets batters out) |
| Tool | What it does |
|---|---|
get_match_impact |
Context-weighted impact scores for every player in a match — batting, bowling, fielding combined |
get_career_impact |
Aggregated impact scores across a player's career or filtered matches |
get_player_form |
Last N innings with individual scores, strike rates, and form summary |
| Tool | What it does |
|---|---|
get_innings_progression |
Over-by-over scoring progression for a match innings |
Every tool supports filters: format (Test/ODI/T20/IT20), gender, team, opposition, venue, city, season, tournament, and date range.
git clone https://github.com/mavaali/cricket-mcp.git
cd cricket-mcp
npm install
This downloads all Cricsheet data (~94 MB ZIP, 21,000+ matches) and loads it into a local DuckDB database:
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
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. Takes seconds.
For a full rebuild (e.g., to pick up Cricsheet corrections to historical data):
npm run ingest -- --force
Cricsheet data doesn't include player attributes like batting hand or bowling style. The repo includes data/player_meta.csv (from the cricketdata R package, 16K players) which adds these attributes. Run this after your first ingest:
npm run enrich -- --csv data/player_meta.csv
This enables the get_style_matchup tool — e.g., "How does Kohli bat against left-arm pace?" or "Bumrah's record against left-handers".
Note: The MCP server must not be running when you enrich (DuckDB allows only one write connection). Quit Claude Desktop first, run the command, then reopen.
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.
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.
Instead of a local DuckDB file, cricket-mcp can read Delta tables directly from a Fabric lakehouse via OneLake. All 26 tools work unchanged — DuckDB's delta and azure extensions handle the reads.
Prerequisites:
az login)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
envblock 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.
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.
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.
Uses get_matchup with batter_name: "Kohli", bowler_name: "Hazlewood", match_type: "ODI".
Uses get_phase_stats with phase: "death", perspective: "bowling", event_name: "Indian Premier League", sort_by: "economy".
Uses get_situational_stats with situation: "chasing", player_name: "Kohli", match_type: "ODI".
Uses get_milestone_tracker with milestone_type: "runs", threshold: 10000, match_type: "ODI".
Uses get_what_if with player_name: "Kohli", perspective: "batting", exclude_bowler: "Hazlewood", match_type: "ODI".
Uses get_tournament_summary with event_name: "Indian Premier League", season: "2024".
Uses get_toss_analysis with match_type: "T20".
Uses get_head_to_head with team1: "India", team2: "Australia", match_type: "Test".
Uses get_style_matchup with player_name: "Kohli", perspective: "batting", grouping: "arm".
Uses get_style_matchup with player_name: "Bumrah", perspective: "bowling".
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.
Uses get_emerging_players with perspective: "batting", match_type: "T20".
Uses get_discipline_stats with perspective: "bowling", phase: "death", event_name: "Indian Premier League", sort_by: "dot_ball_pct".
ingest command downloads, parses, and loads this into a local DuckDB database — a columnar analytics engine that eats aggregation queries for breakfast.Four tables in a star schema:
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.
| Format | Earliest match in dataset | Notes |
|---|---|---|
| Tests | ~Dec 2001 | Covers the 2001/02 season onwards. Players whose careers were primarily pre-2002 (Bradman, Gavaskar, Border, etc.) will be absent or severely underrepresented. |
| ODIs | ~Jun 2002 | Includes the 2003 World Cup onwards. The first ~30 years of ODI cricket (1971-2002) are not covered — no Kapil Dev 175, no 1996 World Cup. |
| T20Is | ~Feb 2005 | Near-complete from the format's inception (first T20I was Feb 2005). |
| T20 (domestic) | ~Apr 2008 | IPL Season 1 onwards. Also includes BBL, CPL, PSL, SA20, and other domestic T20 leagues where Cricsheet has coverage. |
Data is updated regularly and includes matches through early 2026 at time of writing.
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.
get_match_impact, get_career_impact, get_player_form) that compute context-weighted impact scores combining batting contribution, bowling wicket quality + economy, and fielding--transport http --port 3000 starts an HTTP server for remote hosting with session management and CORS supportdocker build && docker run to deployget_matchup now handles specific matchups, batter-vs-team breakdowns, and matchup leaderboards in one toolbowling_style_broad and bowling_style_arm columns during enrichment — eliminates per-row CASE expressions at query timesearch_players to a players-only query (no more JOIN on 10.9M deliveries)delta + azure extensions (--backend onelake).vscode/mcp.json configuration documentednpm run enrich loads batting/bowling style metadata from bundled CSV (16K players from cricketdata R package)get_style_matchup tool: query batting stats by bowling style (pace/spin, arm categories) or bowling stats by batting handBOWLING_WICKET_KINDS not interpolating in SQL template literals (affected all wicket-counting queries)get_matchup replaces separate batter-vs-bowler / bowler-vs-batter tools, get_player_stats replaces separate batting / bowling stats toolsBOWLING_WICKET_KINDS, PHASE_OVERS) to reduce duplicationnpm run update) using Cricsheet's recent match feedsAll data comes from Cricsheet, which provides free, open cricket data. Massive thanks to them for making this possible.
MIT
Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.
{
"mcpServers": {
"cricket-mcp": {
"command": "npx",
"args": []
}
}
}