Duckworth MCP

达克沃斯mcp

板球分析MCP服务器——由DuckDB提供支持的逐球统计、记录和见解。跟随 @达克沃斯mcp 数据驱动的板球见解。

用简单的英语提问，并从9000多场国际和国内比赛的450万次交付中获得答案。想想ESPNcricinfo的统计大师，但很健谈。

里面是什么

• 9063场比赛 （测试，ODI，T20Is）男子和女子板球（2001年12月至2026年3月）
• 4.5M逐球交付 解析自 Cricsheet JSON档案
• 17793名玩家 具有可选的元数据丰富功能（击球手、保龄球风格、扮演角色）
• 46工具 涵盖击球、保龄球、防守、对决、阶段、合作伙伴关系、DRS、锦标赛、系列赛、追逐、场地等
• 一 run_query 当结构化工具无法解决您的问题时，即席SQL的逃逸窗口

______________________________________________________________________

开始

先决条件

您需要安装两件事：

1. Python 3.13+ --检查一下 python3 --version

1. 紫外线 （Python包管理器）--安装时使用：

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

步骤1：克隆并安装

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

步骤2：摄入匹配数据

这将下载约200 MB的Cricsheet档案并将其加载到本地DuckDB数据库中。第一次大约需要15分钟。

uv run duckworth-mcp ingest

步骤3：丰富玩家元数据（可选但推荐）

为约80%的玩家增加击球手、保龄球风格和游戏角色。启用匹配查询，如“Kohli vs左臂配速”。

uv run duckworth-mcp enrich

第四步：联系克劳德

选择您使用的客户端：

Claude Desktop (Mac / Windows app)

打开配置文件：

• 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

或者在Claude Desktop中： 设置>开发人员>编辑配置.

添加此（替换 /path/to/duckworth-mcp 根据您的实际路径）：

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

退出并重新启动Claude Desktop 以使变更生效。您应该看到一个锤子图标，表示MCP工具可用。

Claude Code (CLI / VS Code / JetBrains)

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

或者通过交互方式添加 /mcp 克劳德代码内部。

HTTP transport (other MCP clients)

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

步骤5：验证它是否有效

问克劳德这些问题中的任何一个：

“数据库中有多少个匹配项？”

“谁拥有最多的测试世纪？”

“比较Kohli和Root自2020年以来的测试击球率”

如果你得到统计数据，你就准备好了。

______________________________________________________________________

你可以问什么

从简单开始，然后深入：

基础

• “谁在2023年世界杯上得分最多？”
• “给我看看印度对澳大利亚的测试记录”
• “Jasprit Bumrah的T20I保龄球平均水平是多少？”

比较

• “比较Kohli和Williamson的ODI职业生涯统计数据”
• “Kohli在测试中是如何对抗速度与旋转的？”
• “追踪罗希特·夏尔马的ODI世纪时间表”

深度分析

• “T20I追逐时击球率最高的5名击球手死亡人数”
• “如果没有对阵斯里兰卡的局数，Kohli的ODI平均值会是多少？”
• “哪些活跃玩家最接近10000次测试？”

锦标赛和系列赛

• “比较2023年和2019年ODI世界杯——平均得分、跑动率、最大胜利”
• “IPL 2024与经济体顶级投球手排名”

看 示例_QUERIES.md 用于27个更复杂的多工具提示。

______________________________________________________________________

CLI参考

选项

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

______________________________________________________________________

工具

46种工具按类别排列。大多数人接受常见的过滤器： match_type, gender, team, opposition, venue, city, season, event_name, date_from, date_to.

玩家统计

火柴

记录和排行榜

团队和正面交锋

配对

阶段和情况

合作伙伴关系

里程碑和进展

系列赛和锦标赛

场馆

DRS

分析

追逐

淘汰赛

额外内容

比赛选手

安全舱口

______________________________________________________________________

数据源

Cricsheet（初级）

所有比赛数据均来自 Cricsheet，它以JSON格式提供免费的逐球数据。下载了七个ZIP存档：

• tests_male, odis_male, t20s_male
• tests_female, odis_female, t20s_female
• ipl （国内）

测试的覆盖范围从2001年12月开始，ODI从2002年6月开始，T20I从2005年2月开始。其他国内联赛（BBL、The Hundred等）可从Cricsheet获得，但尚未包括在内。

玩家注册表(people.csv)也从Cricsheet下载，提供玩家ID和ESPNcricinfo和Cricbuzz的交叉引用。

蟋蟀数据R包（增强版）

Cricsheet数据不包括击球手或保龄球风格等球员属性。这 enrich 命令下载 player_meta.csv （来源于 板球数据 R包，约16K玩家），并使用以下内容更新玩家表：

注： 当您进行富时，MCP服务器不得运行（DuckDB只允许一个写连接）。先停止服务器，运行 enrich，然后重新启动。

______________________________________________________________________

数据库模式

包含14个表的星型架构：

尺寸表： players, venues

核心事实表： matches, innings, deliveries

派生表： series, batting_scorecard, bowling_scorecard, partnerships, fall_of_wickets, milestones, drs_reviews, playing_xi, match_officials

看 src/duckworth_mcp/ingest/schema.sql 对于完整的DDL和 src/duckworth_mcp/ingest/indexes.sql 用于分析指标。

______________________________________________________________________

已知限制

1. 玩家丰富覆盖范围 --板球数据CSV涵盖了约18000名球员中的约16K人（80%）。丰富率各不相同：击球手（80%）、保龄球风格（67%）、角色扮演（27%）。来自联盟国家和国内联赛的球员不太可能拥有元数据。

1. 无实时数据 --所有数据均为历史数据，来源于Cricsheet文件下载。使用 update 取消最近完成的比赛。

1. DuckDB单作者 --DuckDB一次只允许一个写连接。运行前必须停止MCP服务器 ingest, update，或 enrich.

1. 船长/守门员旗 --The playing_xi 表格包括 is_captain 和 is_keeper 列，但Cricsheet JSON v2不会对这些列进行注释。他们仍然 FALSE 对于所有条目。

______________________________________________________________________

故障排除

“服务器无法启动”/Claude看不到工具

• 确保你跑了 uv run duckworth-mcp ingest 首先，服务器需要数据库的存在。
• 检查配置中的路径是绝对的，而不是相对的。
• 完全重新启动Claude Desktop（退出，而不仅仅是关闭窗口）。

查询“未找到数据”

• 检查匹配类型拼写： Test, ODI, T20 （不是 T20I --Cricsheet用途 T20 国内和 IT20 国际T20）。
• 使用 search_players 首先验证数据库中的确切玩家姓名。
• 尝试更广泛的过滤器（删除日期范围或特定事件）。

摄入失败或超时

• 第一次运行下载约200 MB。如果您的连接速度较慢，则可能会超时。重新运行 uv run duckworth-mcp ingest --它从中断的地方继续。
• 如果DuckDB报告锁错误，请确保没有其他进程（包括MCP服务器）正在使用该数据库。

“uv：找不到命令”

• 安装紫外线： curl -LsSf https://astral.sh/uv/install.sh | sh （Mac/Linux）或 brew install uv.
• 安装后重新启动终端。

______________________________________________________________________

建筑

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

发展

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

致谢

• Cricsheet --使这成为可能的逐球数据
• 板球数据 R包——球员元数据（击球/保龄球风格、扮演角色）
• 马瓦利/板球mcp --启发这个项目的原始板球MCP服务器。玩家丰富管道和几个工具设计借鉴了他们的工作。

许可证

麻省理工学院