内容
# 数据分析服务器
<!-- mcp-name: io.github.haiiibin/data-profiler-mcp -->
[](https://github.com/haiiibin/data-profiler-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/data-profiler-mcp/)
[](https://pypi.org/project/data-profiler-mcp/)
[](https://pypi.org/project/data-profiler-mcp/)
[](https://glama.ai/mcp/servers/haiiibin/data-profiler-mcp)
[](LICENSE)
> 一个 [MCP](https://modelcontextprotocol.io) 服务器，允许大型语言模型（LLM）理解任何表格数据文件：指向一个 CSV、Parquet、Excel 或 JSON 文件，获取模式、分布、数据质量标志和数据类型建议，以结构化的 JSON 返回。
停止粘贴 `df.head()` 和 `df.info()` 到聊天中。询问你的助手 *"分析 `sales.csv`"*，它会自己读取文件，然后告诉你文件的内容、存在的问题以及如何更高效地加载它。
与 **Claude Desktop**、**Claude Code**、**Cursor** 或任何 MCP 兼容的客户端配合使用。
---
## 功能
六种聚焦的工具，都返回干净的 JSON：
| 工具 | 功能描述 |
|---|---|
| `profile_dataset` | 一次调用概述：形状、内存、缺失值摘要、重复行、每列摘要和纯语言质量标志。 |
| `preview_data` | 前几行 / 后几行 / 随机抽样 `n` 行作为真实记录。 |
| `column_stats` | 深入研究一列：完全的百分位数、偏度 / 峰度、异常值（IQR）、直方图或顶部值 + 文本的字符串长度。 |
| `detect_quality_issues` | 数据质量审计：重复项、高缺失和常数列、数字存储为文本、混合类型列、空格填充、可能的 ID，按严重性分组。 |
| `suggest_dtypes` | 节省内存 / 类型修复建议（文本到数字，低基数到 `category`，整数 / 浮点缩减）以及估计的节省。 |
| `compare_datasets` | 差异两个文件：添加 / 删除列、数据类型更改、行数差异以及每列空值率和均值并排。 |
支持的格式：**CSV、TSV、Parquet、Excel（`.xlsx`/`.xls`）、JSON 和 JSON Lines**。大型文件读取到行上限并明确标记为采样。
---
## 安装
需要 Python 3.10+。
```bash
# 使用 uv（推荐）
uv tool install data-profiler-mcp
# 或使用 pip
pip install data-profiler-mcp
```
或直接从源码运行而无需安装：
```bash
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\`）并添加：
```json
{
"mcpServers": {
"data-profiler": {
"command": "data-profiler-mcp"
}
}
}
```
从源码运行而不是安装？指向检出：
```json
{
"mcpServers": {
"data-profiler": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/data-profiler-mcp", "run", "data-profiler-mcp"]
}
}
}
```
重启 Claude Desktop，工具出现在插件图标下。
### Claude Code
```bash
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`
```jsonc
{
"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`
```jsonc
{
"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." }
]
}
```
---
## 工作原理
服务器基于 [FastMCP](https://github.com/modelcontextprotocol/python-sdk) 构建，并使用 pandas 读取文件（加上 pyarrow 用于 Parquet 和 openpyxl 用于 Excel）。每个工具返回一个纯粹的、可 JSON 序列化的字典，NumPy 标量、`NaN` / `inf` 和时间戳规范化后，输出可以直接返回给模型。不会写入磁盘，数据也不会离开您的机器。
---
## 开发
```bash
uv venv
uv pip install -e ".[dev]"
uv run pytest
```
---
## 许可证
MIT。参见 [LICENSE](LICENSE)。
