data-profiler-mcp

data-profiler-mcp

一个 MCP 服务，可让大模型理解任何表格数据文件：指定一个 CSV、Parquet、Excel 或 JSON 文件，即可获得结构化 JSON 格式的架构、分布、数据质量标记和数据类型建议。

不用再把 df.head() 和 df.info() 粘贴到聊天中。告诉助手 “分析 sales.csv”，它就会自行读取文件，然后告诉你文件中有什么、有哪些问题，以及如何更高效地加载数据。

适用于 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的客户端。

---

功能

七个专用工具，均返回简洁的 JSON：

工具	功能
profile_dataset	一次调用即可概览：形状、内存、缺失值摘要、重复行、逐列摘要和通俗易懂的质量标记。
preview_data	以真实记录形式展示前 n 行、后 n 行或随机抽取的 n 行。
column_stats	深入分析某一列：完整百分位数、偏度/峰度、离群值（IQR）、直方图，或文本的常见值及字符串长度。
detect_quality_issues	数据质量审计：重复项、高缺失率列和常量列、以文本形式存储的数字、混合类型列、空白填充、疑似 ID，并按严重程度分组。
suggest_dtypes	节省内存/修正类型的建议（文本转数值、低基数列转为 category、整数/浮点数降精度），并估算节省空间。
compare_datasets	对比两个文件：新增/删除的列、数据类型变化、行数差异，以及并排比较各列的空值率和均值。
correlation_matrix	数值列之间的相关性（Pearson / Spearman / Kendall）：按强度排列的列对、|r| >= 0.9 时的多重共线性标记，以及通过 column 对目标列与其余列进行排序。

支持的格式：CSV、TSV、Parquet、Excel（.xlsx/.xls）、JSON 和 JSON Lines。大型文件最多读取指定行数，并明确标记数据为抽样结果。

手边没有数据集？examples/sample.csv 是一个小型销售数据导出文件，其中刻意加入了数据质量问题（缺失地区、重复行、常量列、空白填充）——让助手 “分析 examples/sample.csv”，看看它会标记出什么。

---

安装

无需安装即可试用：打开 Glama 服务页面，使用 Try in Browser 在沙盒中调用工具（仓库在 /app/examples/sample.csv 提供了 examples/sample.csv 文件供分析）。

需要 Python 3.10+。

需要 MCP Python SDK 2.x（mcp>=2,<3）。上游已停止为 SDK 1.x 添加功能，本项目也不再支持；最后一个支持该版本的发布版是 0.3.0。

# with uv (recommended)
uv tool install data-profiler-mcp

# or with pip
pip install data-profiler-mcp

或者直接从源代码运行，无需安装：

git clone https://github.com/haiiibin/data-profiler-mcp
cd data-profiler-mcp
uv run data-profiler-mcp

---

配置客户端

Claude Desktop

编辑 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）并添加：

{
  "mcpServers": {
    "data-profiler": {
      "command": "data-profiler-mcp"
    }
  }
}

如果要从源代码运行，而不是安装，请将路径指向检出目录：

{
  "mcpServers": {
    "data-profiler": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/data-profiler-mcp", "run", "data-profiler-mcp"]
    }
  }
}

重启 Claude Desktop，工具就会显示在插件图标下。

Claude Code

claude mcp add data-profiler -- data-profiler-mcp

---

使用方法

连接后，直接与助手对话：

• “分析 ~/data/sales_2025.csv，告诉我里面有什么。”
• “customers.parquet 中是否存在数据质量问题？”
• “随机显示 events.jsonl 中的 20 行。”
• “提供 revenue 列的完整统计信息，包括离群值。”
• “如何减少这个 DataFrame 的内存用量？”
• “snapshot_jan.csv 和 snapshot_feb.csv 之间有什么变化？”

示例：profile_dataset

{
  "file": { "name": "sample.csv", "format": "csv", "size_human": "14.2 KB" },
  "shape": { "rows": 201, "columns": 13, "sampled": false },
  "memory_usage_human": "78.4 KB",
  "missing_summary": { "total_missing_cells": 561, "pct_missing": 21.5, "columns_with_missing": 3 },
  "duplicate_rows": { "count": 1, "pct": 0.5 },
  "columns": [
    {
      "name": "price", "dtype": "float64", "inferred_type": "float",
      "non_null": 201, "null": 0, "unique": 51,
      "stats": { "min": 0.0, "max": 100000.0, "mean": 521.3, "median": 24.0 }
    }
  ],
  "quality_flags": [
    "[high] empty_col: Column is entirely empty (all values missing).",
    "[warning] const: Column holds a single constant value; it carries no information.",
    "[warning] numeric_text: Every value parses as a number but the column is stored as text."
  ]
}

示例：detect_quality_issues

{
  "issue_count": 8,
  "severity_counts": { "high": 2, "warning": 4, "info": 2 },
  "issues": [
    { "column": "empty_col", "issue": "all_missing", "severity": "high",
      "detail": "Column is entirely empty (all values missing)." },
    { "column": "numeric_text", "issue": "numeric_stored_as_text", "severity": "warning",
      "detail": "Every value parses as a number but the column is stored as text." }
  ]
}

---

工作原理

此服务基于 MCP Python SDK 的 MCPServer 构建，并使用 pandas 读取文件（Parquet 使用 pyarrow，Excel 使用 openpyxl）。每个工具都会返回普通的、可序列化为 JSON 的字典，并对 NumPy 标量、NaN/inf 和时间戳进行标准化，因此输出可直接安全地交给模型。不会向磁盘写入任何内容，也不会有任何数据离开你的设备。

---

开发

uv venv
uv pip install -e ".[dev]"
uv run pytest

---

许可证

MIT。详见 LICENSE。