CSV Analyzer MCP Server

CSV Analyzer MCP 服务

一个轻量级 MCP 服务，将 CSV 分析封装为工具，供任何兼容 MCP 的客户端调用。

传入原始 CSV 内容，即可获取结构化统计信息——行数、类型检测、空值率、重复项、分布、异常值检测等，并以 JSON 或 Markdown 格式返回。

---

什么是 MCP？

Model Context Protocol 是一项开放标准，允许 AI 助手调用外部工具。此服务将 CSV 分析封装为 MCP 工具，因此你可以向 Claude 提出诸如 “分析这个 CSV，并告诉我哪些列的空值最多” 或 “筛选 revenue > 10000 的行，然后分析结果” 之类的问题，并获取实际计算出的结果。

---

功能

• 列级分析 — 类型检测、空值率、唯一值、最小值/最大值/平均值/中位数/标准差、四分位数、最常见值、日期范围
• 频率分布 — 针对任意列，按排名返回值计数及百分比
• 异常值检测 — 使用 IQR 和 z-score 方法检测所有数值列中的异常值
• 行筛选 — 按列条件筛选，并将结果用于后续分析
• 数据预览 — 在分析前以 Markdown 表格查看前 N 行
• CSV 比较 — 按架构、行内容或两者比较两个文件的差异
• 数据清理 — 分析前可选择去重和移除空值行
• 双输出格式 — 提供适用于程序处理的结构化 JSON，或便于阅读摘要的 Markdown
• 自定义分隔符 — 支持逗号、分号、制表符、竖线或任意分隔符
• 基于内容 — 接受原始 CSV 文本，而非文件路径，因此安全且兼容远程环境

---

安装

前置条件： Python ≥ 3.12 和 uv

git clone https://github.com/juanmaalt/csv_analyzer_mcp_server.git
cd csv_analyzer_mcp_server
uv sync

---

连接到 MCP 客户端

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json （macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "csv_analyzer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/csv_analyzer_mcp_server",
        "python",
        "main.py"
      ]
    }
  }
}

Cursor / VS Code（MCP 扩展）

{
  "mcp": {
    "servers": {
      "csv_analyzer": {
        "command": "uv",
        "args": [
          "run",
          "--directory",
          "/absolute/path/to/csv_analyzer_mcp_server",
          "python",
          "main.py"
        ]
      }
    }
  }
}

保存配置后，重启客户端。所有工具都会显示在可用工具列表中。

---

可用工具

analyze_csv

对 CSV 文件进行完整的统计分析。返回每列的摘要，包括类型、空值率、唯一值计数和特定类型的统计数据。

参数	类型	默认值	描述
csv_content	str	必填	完整的 CSV 文本内容（不是文件路径）
delimiter	str	","	分隔各值的字符
remove_duplicates	bool	True	分析前移除完全重复的行
remove_non_valid_data	bool	True	分析前移除包含缺失/空字段的行
output_format	str	"json"	"json" 或 "markdown"

JSON 输出结构：

{
  "total_rows": 38,
  "rows_removed": 2,
  "columns": {
    "age": {
      "null_count": "N/A",
      "null_percentage": "N/A",
      "duplicate_count": "N/A",
      "unique_values": 22,
      "type": "int",
      "min": 19,
      "max": 74,
      "avg": 43.5,
      "median": 42.0,
      "std": 14.2,
      "q25": 31.0,
      "q75": 57.0
    },
    "plan_type": {
      "null_count": "N/A",
      "null_percentage": "N/A",
      "duplicate_count": "N/A",
      "unique_values": 3,
      "type": "string",
      "most_repeated_value": "Premium",
      "top_values": [
        {"value": "Premium", "count": 18},
        {"value": "Basic", "count": 12},
        {"value": "Enterprise", "count": 8}
      ]
    }
  }
}

---

get_csv_preview

将 CSV 的前 N 行以 Markdown 表格形式返回。适用于运行完整分析前查看结构和值。不执行任何清理。

参数	类型	默认值	描述
csv_content	str	必填	完整的 CSV 文本内容
delimiter	str	","	分隔各值的字符
n_rows	int	5	要返回的行数

输出示例：

| customer_id | age | plan_type | monthly_fee |
| --- | --- | --- | --- |
| 1001 | 34 | Premium | 49.99 |
| 1002 | 27 | Basic | 19.99 |

---

filter_csv

按列条件筛选行，并将结果作为 CSV 字符串返回。输出可直接传入 analyze_csv 或任何其他工具。

Parameter	Type	Default	Description
csv_content	str	required	完整的 CSV 文本内容
column	str	required	要筛选的列名
operator	str	required	以下运算符之一：>、<、>=、<=、==、!=、contains
value	str	required	用于比较的值（自动转换为列类型）
delimiter	str	","	分隔值的字符

支持的运算符：

Operator	Behavior
> < >= <=	数值比较
== !=	相等性比较（适用于任何类型）
contains	对字符串列进行不区分大小写的子字符串匹配

---

get_column_distribution

返回指定列的频率排名表，显示每个值出现的次数及其占总行数的百分比。

Parameter	Type	Default	Description
csv_content	str	required	完整的 CSV 文本内容
column	str	required	要分析的列名
delimiter	str	","	分隔值的字符
top_n	int	10	返回值的最大数量

输出示例：

[
  {"value": "Premium", "count": 18, "percentage": 45.0},
  {"value": "Basic", "count": 12, "percentage": 30.0},
  {"value": "Enterprise", "count": 8, "percentage": 20.0}
]

---

detect_outliers

使用 IQR 或 z-score 查找数值列中包含异常值的行。返回标记出的行，以及列名、值和原因。

Parameter	Type	Default	Description
csv_content	str	required	完整的 CSV 文本内容
delimiter	str	","	分隔值的字符
method	str	"iqr"	"iqr" 或 "zscore"
columns	list[str]	None	要检查的特定列。若省略，则检查所有数值列

方法：

• iqr — 标记小于 Q1 - 1.5 * IQR 或大于 Q3 + 1.5 * IQR 的值
• zscore — 标记与均值相差超过 3 个标准差的值

输出示例：

[
  {"row_index": 4, "column": "monthly_fee", "value": 999.99, "reason": "outside IQR bounds [10.5, 89.3]"},
  {"row_index": 21, "column": "age", "value": 3, "reason": "outside IQR bounds [22.0, 68.0]"}
]

---

compare_csvs

按架构（列差异）和/或行内容比较两个 CSV 文件。适用于检测同一数据集不同版本之间的变更。

Parameter	Type	Default	Description
csv_content_a	str	required	第一个文件的完整 CSV 文本内容
csv_content_b	str	required	第二个文件的完整 CSV 文本内容
delimiter	str	","	两个文件中分隔值的字符
mode	str	"both"	"schema"、"rows" 或 "both"

输出示例（mode="both"）：

{
  "schema": {
    "columns_only_in_a": ["notes"],
    "columns_only_in_b": ["region"],
    "common_columns": ["client", "revenue", "date"]
  },
  "rows": {
    "total_rows_a": 25,
    "total_rows_b": 28,
    "rows_only_in_a": 4,
    "rows_only_in_b": 7,
    "common_rows": 21
  }
}

---

组合工具

这些工具专为串联使用而设计。以下是一些实用模式：

# Preview first, then analyze
get_csv_preview → analyze_csv

# Filter a subset, then analyze it
filter_csv (churned == True) → analyze_csv

# Check distribution before deciding how to filter
get_column_distribution → filter_csv → analyze_csv

# Find outliers, then filter them out and re-analyze
detect_outliers → filter_csv (!= outlier_value) → analyze_csv

---

配置

设置从项目根目录下的 .env 文件加载：

Variable	Default	Description
MAX_ROWS_TO_ANALYZE	500	每个请求处理的最大行数
DEFAULT_OUTPUT_FORMAT	markdown	默认输出格式
MAX_PREVIEW_ROWS	10	摘要中的预览行数
NULL_THRESHOLD_WARNING	0.3	超过此空值率时显示警告
OUTLIER_STDDEV_CUTOFF	3.0	异常值检测的 Z-score 截止值

---

项目结构

csv_analyzer_mcp_server/
├── core/
│   ├── loader.py        # CSV string → pandas DataFrame
│   ├── analyzer.py      # Per-column statistics, distribution, outlier detection, comparison
│   ├── formatter.py     # JSON / Markdown output, table preview
│   └── transformer.py   # Column name normalization, row filtering
├── config/
│   └── settings.py      # Environment-based configuration
├── data/                # Sample CSV files for testing
├── main.py              # MCP server entry point — all tool definitions
├── pyproject.toml       # Project metadata and dependencies
└── .env                 # Local configuration (not committed)

---

示例数据

data/ 中包含三个用于测试的示例 CSV 文件：

File	Rows	Description
sample_data_usage.csv	40	电信客户使用情况（年龄、套餐、数据、流失）
sample_heart_checks.csv	40	医疗记录（胆固醇、血压、糖尿病、心脏病）
sample_project_revenue.csv	25	含有刻意设置的缺失值的项目计费数据

---