README.md
A cricket stats nerd's dream, wired directly into Claude.
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 (25 total)
Player Stats
| 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 |
Match & Team Queries
| 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 |
Records & Leaderboards
| 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 |
Venue & Partnerships
| Tool | What it does |
|---|---|
get_venue_stats |
Ground stats — avg scores, bat-first win %, highest/lowest totals |
get_partnerships |
Highest batting partnerships |
Batter vs Bowler Matchups
| 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 |
Phase & Situation Analysis
| 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 % |
Team & Tournament
| 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 |
Career & Trends
| 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 |
Fielding & Dismissals
| 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) |
Innings Analysis
| 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.
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 # l
Tools (25)
search_playersFuzzy name search with career summaryget_player_statsFull batting or bowling statssearch_matchesFind matches with filters and paginationget_head_to_headTeam vs team W/L/D/T recordget_match_scorecardComplete batting and bowling card for any matchget_batting_recordsRank players by runs, avg, SR, 100s, 50s, 6s, 4s, HSget_bowling_recordsRank players by wickets, avg, econ, SR, 5wiget_venue_statsGround stats including avg scores and win percentagesget_partnershipsHighest batting partnershipsget_matchupHead-to-head stats between players or batter vs team bowlingget_style_matchupBatter vs bowling styles or bowler vs batting handget_phase_statsBatting/bowling stats by powerplay, middle, or death oversget_situational_statsStats while chasing, setting, or under pressureget_toss_analysisToss impact on outcomes by venue, team, or formatget_discipline_statsDot ball percentage, wide rate, and boundary percentageget_team_formRecent form including last N results and run ratesget_tournament_summaryStandings and top performers for any tournamentget_milestone_trackerPlayers near career milestonesget_emerging_playersPlayers whose recent stats outperform career baselineget_what_ifRecalculate career stats excluding specific opponents or venuesget_season_statsYear-by-year career breakdownget_player_comparisonSide-by-side comparison of two playersget_fielding_statsCatches, stumpings, and run outs per fielderget_dismissal_analysisBreakdown of how a player gets out or gets batters outget_innings_progressionOver-by-over scoring progression for a match inningsConfiguration
claude_desktop_config.json
{ "mcpServers": { "cricket-mcp": { "command": "node", "args": ["/path/to/cricket-mcp/index.js"] } } }Try it
→How does Virat Kohli bat against Josh Hazlewood in ODIs?
→Who are the best death bowlers in the IPL by economy rate?
→What is Kohli's batting average while chasing in ODIs?
→Which bowlers have the best dot ball percentage at the death?
→Break down Rohit Sharma's record against each of England's bowlers.