cricket-mcp

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"

Tools (26 total)

Player Stats

Match & Team Queries

Records & Leaderboards

Venue & Partnerships

Batter vs Bowler Matchups

Phase & Situation Analysis

Team & Tournament

Career & Trends

Fielding & Dismissals

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

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

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

npm run ingest -- --force

Enrich player metadata

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.

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.

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

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

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

Changelog

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