jDataMunch MCP

jDataMunch MCP：面向 AI Agent 的表格数据检索

jDataMunch 是一款 MCP 服务，面向编码 Agent 和分析师，可针对 CSV、Excel、Parquet 和 JSONL 文件回答问题，无需将数据行粘贴到上下文窗口中。

只需为数据集建立一次索引，即可检索列概况、筛选后的行、服务端聚合结果以及跨数据集联接——这样，包含百万行的文件只需数千个 token，而非数百万个。

安装 · 快速入门 · 基准测试 · 商业许可

个人使用免费。 商业用途需要付费许可——条款如下。

---

为什么选择 jDataMunch？

问题所在。 Agent 探索电子表格的默认方式是将其粘贴到提示词中。一个包含百万行、大小为 255 MB 的 CSV 文件，照此处理约需 1.11 亿个 token；而且，即使只是回答“这里有哪些列？”，模型仍得对百万行数据进行推理。

实现机制。 jDataMunch 会先对文件进行一次分析——包括列、类型、基数、空值率和分布——并将结果保存在本地。之后的查询直接针对数据本身运行，而不是针对提示词中的副本：筛选、聚合和联接都在服务端执行，并且只返回结果。

最终效果。 数据概览问题可通过分析结果回答；行级问题则返回匹配的行。原始文件不会进入上下文窗口。

---

证据

基于真实公开数据集的测量结果，而非估算值。完整测试框架和逐项查询结果见 benchmarks/。

数据集： LAPD 犯罪记录——1,004,894 行、28 列、255 MB 基准值： 粘贴原始文件需要 111,028,360 个 token describe_dataset： 约 3,849 个 token——减少 25,333 倍 方法与测试框架 · 完整结果

任务	不使用 jDataMunch	使用 jDataMunch	减少幅度
了解数据集的结构	粘贴 1.11 亿个 token	describe_dataset → 约 3,849 个 token	约 25,000 倍
查看架构 + 深入了解一列	粘贴 1.11 亿个 token	describe_dataset + describe_column → 约 4,400 个 token	约 25,000 倍
筛选匹配的行	加载全部 100 万行	使用筛选条件调用 get_rows → 仅返回匹配行	约 99% 以上
按类别计数	返回所有行，由模型执行聚合	aggregate(group_by=[...]) → 21 行	约 99.9%

这些数字的含义与局限。 减少幅度是相对于粘贴完整文件而言的，这是简单 Agent 的做法，也反映在 token 费用中。它并非相对于胜任的人类分析师而言，因为他们根本不会粘贴 255 MB 的 CSV。减少倍数会随文件大小变化：一份 200 行的电子表格可节省的 token 少得多，客观来说，差异接近于“没有明显差别”。

同一次运行中的典型延迟：针对单列调用 describe_column，耗时 22–33 毫秒，约 600 个 token。

---

安装

**要求：**Python 3.10+、任意兼容 MCP 的客户端。

无需安装。jdatamunch-mcp 是一个 stdio MCP 服务，没有 CLI 子命令，因此无需将任何内容放到 PATH 中——让客户端调用 uvx，它就会按需获取并运行该服务。

Claude Code 设置：

claude mcp add jdatamunch -- uvx jdatamunch-mcp

无需其他操作。还没有 uv？

要读取 Excel 或 Parquet？这些格式需要安装可选扩展，通过 --from 参数传给 uvx：

claude mcp add jdatamunch -- uvx --from "jdatamunch-mcp[excel,parquet]" jdatamunch-mcp

更倾向于持久安装？

命令	适用场景
uv tool install jdatamunch-mcp	你希望只解析一次，而不是每次启动时都解析
pipx install jdatamunch-mcp	你已经统一使用 pipx
pip install jdatamunch-mcp	在由你自行管理的虚拟环境中。⚠ 在 PEP 668 发行版（Ubuntu 24.04+、Debian 12+）上会被拒绝——请使用上述两种方式之一。

这里的扩展使用常见的方括号形式：uv tool install "jdatamunch-mcp[excel,parquet]"。注册服务的方式仍然相同；在上方的 claude mcp add 命令中，用 jdatamunch-mcp 替换 uvx jdatamunch-mcp 即可。

重启 Claude Code，然后输入 /mcp——列表中应该会显示 jdatamunch。该列表就是验证步骤；直接运行服务只会让它等待 stdin。

各客户端的完整设置说明（包括 Claude Desktop、Cursor 和 Windsurf）：QUICKSTART.md。

---

快速入门

**前提：**已安装 jDataMunch 并在客户端中注册，且手头有一个 CSV 文件。

所有操作都在 Agent 中完成——无需单独运行索引命令。让它创建索引：

使用 jdatamunch，为 ./data/sales.csv 创建索引

它会调用 index_local，返回数据集名称、行数和列数，以及检测到的类型。然后：

使用 jdatamunch，描述 sales 数据集，并告诉我哪些列包含缺失值。

Agent 会调用 describe_dataset，返回列名、推断类型、基数、空值率和样例值——不会将任何一行读入上下文。_meta.tokens_saved 会报告与加载整个文件相比所节省的开销。

**下一步：**使用 describe_column 查看某列的分布，或使用 aggregate 在服务端进行分组和计数。

---

可以做什么

• 了解从未见过的数据集。describe_dataset、describe_column、sample_rows、get_distribution、get_correlations。
• **无需加载数据行即可查询。**使用带筛选条件的 get_rows、带 group_by 的 aggregate、run_sql，以及在运行前预览开销的 plan_query。
• 跨数据集操作。suggest_joins、suggest_keys、join_datasets。
• 发现数据质量问题。get_dataset_health、data_health_radar、get_data_hotspots（空值率、基数异常、离群值分布）、get_schema_drift、find_unused_columns。
• **预检架构变更。**删除或重命名前，使用 check_column_drop_safe 和 get_schema_impact。
• **按语义搜索。**当你知道想找什么，却不知道它叫什么时，使用 search_data 和 find_similar_columns。
• 从 GitHub 创建索引。index_repo 可直接从仓库获取 CSV、Excel、Parquet 和 JSONL 文件，并按 HEAD SHA 增量处理，也支持私有仓库。

共 39 个工具。完整参考：USER-MANUAL.md。

---

工作原理

所有操作都在本地运行。数据集在你的机器上进行分析，索引也存储在你的机器上；创建索引或查询时都不会涉及托管服务。

data.csv ──► profiler ──► column stats + local index
                                    │
              MCP client ◄── query ─┘   (filters, aggregates, joins
                                         execute server-side)

聚合和筛选直接对存储的数据运行，而不是由模型模拟，因此行数几乎不会影响答案的令牌开销。基于抽样的统计会报告误差范围（标准误差约为 2%），而不会把估算值说成精确值。

---

支持的格式

格式	扩展名	安装额外依赖
CSV / TSV	.csv、.tsv	内置
JSON Lines	.jsonl	内置
Excel	.xlsx、.xls	pip install "jdatamunch-mcp[excel]"
Parquet	.parquet	pip install "jdatamunch-mcp[parquet]"

---

安全与隐私

本地优先。数据会在你的设备上进行分析和索引，不会上传。

基础软件包唯一默认的网络行为是匿名节省量计数器——一个随机 ID 加上汇总的 Token 数量。不包含数据、列名、文件路径或 PII。 可完全选择退出：

JDATAMUNCH_SHARE_SAVINGS=0

只有在你调用 index_repo 时，它才会访问 GitHub，并使用你提供的 Token。只有在你配置嵌入提供商后，才会调用它们。没有调度程序，也不会在后台报告数据。

完整详情（包括各可选额外依赖会引入哪些内容）：SECURITY.md。

---

限制

• 节省量随文件大小而变化。 对于较小的电子表格，差异微乎其微；基准测试数据来自一个 255 MB 的文件。
• 抽样统计基于抽样结果。 对于非常大的文件，分布和相关性数据会给出误差范围，而非精确值。
• Excel 和 Parquet 需要可选额外依赖，这些依赖会引入更多依赖项。
• 默认的 describe_column 不会被标记为 offloadable。 jDataMunch 不会声称索引是最新的，除非它能证明这一点，因此低成本的新鲜度检查会返回 unknown，标注也会采取保守策略。这是有意为之——请参阅标注章节。
• jDataMunch 不会读取代码或散文。 代码符号请使用 jcodemunch-mcp；文档章节请使用 jdocmunch-mcp。

---

可卸载工作标注

JMUNCH_OFFLOADABLE=1（整个套件）或 JDATAMUNCH_OFFLOADABLE=1（仅此服务）会让 describe_column 附带一个提示性的 _meta.offloadable 块，用于标记答案是否足够简单且独立，可以交给更便宜的模型处理。

这只是一个标签，仅此而已。 jDataMunch 不会调用其他模型，不会路由请求，也不会触碰你的 API 密钥。默认关闭；接下来如何处理由你决定。

判定结果有三种状态，并附有原因代码：not_evaluated（“我们未对此进行评估”）不等于 not_offloadable（“这不是简单工作”）。它采取保守策略——任何可能影响答案的未知因素都会导致判定不通过，因为错误地标记为 offloadable 会把实际工作交给一个会对信息缺口胡编乱造的模型。verify_with 会指出用于判定更便宜的模型答案是否正确的调用。

所有三个 jMunch 服务采用完全相同的字段契约，并固定契约摘要；任何一个服务出现偏差都会导致构建失败。

---

文档

文档	内容
QUICKSTART.md	三步完成从零开始到建立索引
USER-MANUAL.md	面向分析师、运维人员和非开发者的完整指南
SECURITY.md	数据处理、网络行为、漏洞报告
benchmarks/METHODOLOGY.md	基准测试的运行方式和衡量内容
CONTRIBUTING.md	开发环境设置和 CLA 要求
CHANGELOG.md	发布历史

---

许可和商业用途

依据 jDataMunch-MCP Dual-Use License 发布（完整条款）。非商业用途免费。商业用途需要购买付费许可证，一次性付费，由 jMunch LLC 出售。

仅限 jDataMunch： Builder，$39（1 位开发者） · Studio，$149（最多 5 位） · Platform，$499（组织范围内的内部部署）

完整 jMunch 套件（代码 + 文档 + 数据）： Trio Builder，$99 · Trio Studio，$449 · Trio Platform，$2,499

个人开发者和非商业项目无需许可证。组织在内部团队中部署 jDataMunch 则需要许可证。

---

支持和项目状态

项目正在积极维护。问题和 Bug 报告请提交至：GitHub Issues。商业许可相关问题请通过 jcodemunch.com 咨询。

这是 jMunch 套件的一部分，另有 jcodemunch-mcp（代码符号）和 jdocmunch-mcp（文档章节）。三者均实现了 jMRI，即开放的检索接口规范——采用相同的响应封装和 Token 统计方式。