板球数据分析服务

duckworth-mcp

Cricket analytics MCP server that uses DuckDB for ball-by-ball stats, records, and insights. Follow @duckworthmcp for data-driven cricket insights.

Ask questions in plain English and get answers from 5 million deliveries across 10,900+ international and domestic matches. It gives the same data as ESPNcricinfo's Statsguru, but as a conversation.

What's inside

• 10,926 matches (Tests, ODIs, T20Is, IPL) for men's and women's cricket (Dec 2001 – Aug 2026)
• 5M ball-by-ball deliveries parsed from Cricsheet JSON archives
• 18,385 players with optional metadata enrichment (batting hand, bowling style, playing role)
• 46 tools across batting, bowling, fielding, matchups, phases, partnerships, DRS, tournaments, series, chases, venues, and more
• A run_query escape hatch for ad-hoc SQL, for questions outside the structured tools

Get started

Prerequisites

You need two things installed:

1. Python 3.13+ — check with python3 --version

2. uv (Python package manager) — install with:

   复制

   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows (PowerShell)
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # or: brew install uv (macOS), winget install astral-sh.uv (Windows)
   

Step 1: Clone and install

git clone https://github.com/ankitksr/duckworth-mcp.git
cd duckworth-mcp
uv sync

Step 2: Ingest match data

This downloads about 200 MB of Cricsheet archives and loads them into a local DuckDB database. It takes about 15 minutes for the first run.

uv run duckworth-mcp ingest

Step 3: Enrich player metadata (optional but recommended)

It adds batting hand, bowling style, and playing role for ~80% of players. It lets you run matchup queries like "Kohli vs left-arm pace".

Note: Stop the MCP server before you run this command — DuckDB lets only one write connection at a time.

uv run duckworth-mcp enrich

Step 4: Connect to Claude

Pick the client you use:

{
  "mcpServers": {
    "duckworth-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/duckworth-mcp", "duckworth-mcp", "serve"]
    }
  }
}

claude mcp add duckworth-mcp -- uv run --directory /path/to/duckworth-mcp duckworth-mcp serve

uv run duckworth-mcp serve --transport http --host 0.0.0.0 --port 8000

Step 5: Make sure it works

Ask Claude any of these:

"How many matches are in the database?"

"Who has the most Test centuries?"

"Compare Kohli and Root's batting averages in Tests since 2020"

If you get stats back, you are ready.

What you can ask

Start simple, then go deep:

Basics

• "Who scored the most runs in the 2023 World Cup?"
• "Show me India's Test record against Australia"
• "What's Jasprit Bumrah's T20I bowling average?"

Comparisons

• "Compare Kohli and Williamson's ODI career stats"
• "How does Kohli bat against pace vs spin in Tests?"
• "Trace Rohit Sharma's ODI century timeline"

Deep analysis

• "Top 5 death-over batters by strike rate in T20Is while chasing"
• "What would Kohli's ODI average be without innings against Sri Lanka?"
• "Which active players are closest to 10,000 Test runs?"

Tournaments and series

• "Compare the 2023 and 2019 ODI World Cups — average scores, run rates, biggest wins"
• "IPL 2024 standings with top bowlers by economy"

See SAMPLE_QUERIES.md for 27 more complex multi-tool prompts.

CLI reference

Options

--transport {stdio,http,sse}   MCP transport (default: stdio)
--host HOST                    HTTP host (default: 0.0.0.0)
--port PORT                    HTTP port (default: 8000)
--db PATH                      Path to DuckDB file (default: ./data/cricket.duckdb)
--csv PATH                     Path to player_meta.csv for enrichment (downloads if omitted)

Tools

The sections below group the 46 tools by category. Most accept common filters: match_type, gender, team, opposition, venue, city, season, event_name, date_from, date_to.

Player stats

Matches

Records and leaderboards

Team and head-to-head

Matchups

Phases and situations

Partnerships

Milestones and progression

Series and tournaments

Venues

DRS

Analysis

Chases

Knockouts

Extras

Player of the Match

Escape hatch

Data sources

Cricsheet (primary)

All match data comes from Cricsheet, which provides free ball-by-ball data in JSON format. duckworth-mcp downloads seven ZIP archives:

• tests_male, odis_male, t20s_male
• tests_female, odis_female, t20s_female
• ipl (domestic)

Coverage begins around Dec 2001 for Tests, Jun 2002 for ODIs, and Feb 2005 for T20Is. Other domestic leagues, for example BBL and The Hundred, are available from Cricsheet. duckworth-mcp does not yet ingest them.

duckworth-mcp also downloads the player registry (people.csv) from Cricsheet. It provides player IDs and cross-references to ESPNcricinfo and Cricbuzz.

cricketdata R package (enrichment)

Cricsheet data does not include player attributes, for example batting hand or bowling style. The enrich command downloads player_meta.csv (from the cricketdata R package, ~16K players) and updates the players table with:

Note: Stop the MCP server before you run enrich — DuckDB lets only one write connection at a time. Restart the server after enrich finishes.

Database schema

The database uses a star schema with 14 tables:

Dimension tables: players, venues

Core fact tables: matches, innings, deliveries

Derived tables: series, batting_scorecard, bowling_scorecard, partnerships, fall_of_wickets, milestones, drs_reviews, playing_xi, match_officials

See src/duckworth_mcp/ingest/schema.sql for the full DDL and src/duckworth_mcp/ingest/indexes.sql for analytical indexes.

Known limitations

1. Player enrichment coverage — The cricketdata CSV has data for ~16K of ~18K players (80%). Enrichment rates vary: batting hand (80%), bowling style (67%), playing role (27%). Players from associate nations and domestic leagues often do not have metadata.

2. No live data — All data is historical. It comes from Cricsheet file downloads. Use update to add recently completed matches.

3. DuckDB single-writer — DuckDB lets only one connection write to the database at a time. Stop the MCP server before you run ingest, update, or enrich.

4. Captain/keeper flags — The playing_xi table includes is_captain and is_keeper columns, but Cricsheet JSON v2 does not have this data. The columns remain FALSE for all entries.

Troubleshooting

"The server does not start" / Claude cannot see the tools

• Make sure you ran uv run duckworth-mcp ingest first — the server needs the database to exist.
• Check the path in your config is absolute, not relative.
• Restart Claude Desktop fully (quit, not just close the window).

"No data found" for queries

• Check the match type spelling: Test, ODI, T20 (not T20I — Cricsheet uses T20 for domestic and IT20 for international T20s).
• Use search_players first to make sure the player name in the database is correct.
• Try broader filters. Remove the date range or the event filter.

Ingestion failed or timed out

• The first run downloads about 200 MB. If your connection is slow, it can time out. Run uv run duckworth-mcp ingest again — it starts again from where it stopped.
• If DuckDB reports a lock error, make sure that no other process — for example, the MCP server — uses the database.

"uv: command not found"

• Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (Mac/Linux) or brew install uv.
• After you install uv, restart your terminal.

Architecture

src/duckworth_mcp/
  __main__.py          CLI entry point (serve | ingest | update | enrich)
  server.py            FastMCP server, mounts all tool modules
  db.py                DuckDB connection management and query helpers
  ingest/
    download.py        HTTP downloads from Cricsheet + cricketdata
    parser.py          JSON → flat dict parser for all match entities
    loader.py          Bulk CSV loader, series derivation, enrichment
    schema.sql         Full DDL (14 tables)
    indexes.sql        Analytical indexes (created after bulk load)
  tools/
    players.py         search_players, get_player_stats, comparison, seasons
    matches.py         search_matches, get_match_scorecard
    batting.py         get_batting_records
    bowling.py         get_bowling_records
    fielding.py        get_fielding_stats
    teams.py           head_to_head, toss_analysis, team_form
    venues.py          get_venue_stats
    matchups.py        get_matchup, get_style_matchup, get_pace_vs_spin
    phases.py          phase_stats, situational_stats
    partnerships.py    partnerships, partnership_records
    milestones.py      match_milestones, milestone_timeline
    series.py          search, detail, comparison, records
    tournaments.py     get_tournament_summary
    drs.py             drs_stats, drs_records, umpire_accuracy
    analysis.py        what_if, emerging_players, discipline, milestone_tracker, declarations
    progression.py     innings_progression
    chases.py          chase_analysis, chase_heroes
    knockouts.py       knockout_stats, team_knockout_record
    extras.py          extras_analysis
    potm.py            potm_leaderboard
    playing_xi.py      get_playing_xi
    officials.py       get_match_officials
    run_query.py       ad-hoc SQL
tests/
  conftest.py          Shared fixtures (in-memory DuckDB, test data)
  test_schema.py       Schema and index creation
  test_parser.py       Cricsheet JSON parser
  test_filters.py      Match filter builder
  test_tools.py        Tool smoke tests
  test_run_query.py    SQL guardrails

Development

uv sync --group dev
uv run ruff check src/
uv run ruff format src/
uv run pytest

Acknowledgements

• Cricsheet — the ball-by-ball data that makes this possible
• cricketdata R package — player metadata (batting/bowling styles, playing roles)
• mavaali/cricket-mcp — the original cricket MCP server that inspired this project. The player enrichment pipeline and several tool designs draw from their work.

License

MIT