AI导哈

CSV分析工具MCP服务器

一个轻量级的MCP服务器，提供CSV分析功能，支持通过任何MCP兼容客户端调用，包括列级分析、异常值检测、数据过滤和比较等功能。

  • by juanmaalt
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 juanmaalt/csv_analyzer_mcp_server

使用说明

CSV分析器MCP服务器

一个轻量级的MCP服务器，它将CSV分析作为任何兼容MCP的客户端都可以调用的工具。

传递原始CSV内容，以JSON或Markdown格式返回结构化统计数据——行数、类型检测、空率、重复、分布、异常检测等。

什么是MCP？

这 模型上下文协议 是一个开放标准，允许AI助手调用外部工具。此服务器将CSV分析作为MCP工具公开，因此您可以向Claude询问以下问题 “分析此CSV并告诉我哪些列的空值最多” 或 “过滤收入>10000的行，然后分析结果” 并得到真实的计算结果。

特性

  • 柱级分析 --类型检测、空率、唯一值、最小值/最大值/平均值/中值/标准差、四分位数、重复次数最多的值、日期范围
  • 频率分布 --任何列的排序值计数（带百分比）
  • 异常值检测 --所有数字列的IQR和z-score方法
  • 行过滤 --按列条件和链过滤以进行进一步分析
  • 数据预览 --在分析之前，将前N行作为Markdown表进行检查
  • CSV比较 --按模式、行内容或两者区分两个文件
  • 数据清理 --分析前可选的重复数据删除和空行删除
  • 双输出格式 --结构化JSON用于编程，Markdown用于可读摘要
  • 自定义分隔符 --逗号、分号、制表符、管道或任何分隔符
  • 基于内容的 --接受原始CSV文本，而不是文件路径，使其安全并与远程环境兼容

安装

先决条件： Python≥3.12 紫外线

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

连接到MCP客户端

克劳德桌面版

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

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

光标/VS代码（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 或任何其他工具。

参数 类型 默认值 说明
csv_content str 必填 完整的CSV文本内容
column str 必填 要筛选的列名
operator str 必填 以下之一： >, <, >=, <=, ==, !=, contains
value str 必需 要比较的值（自动转换为列类型）
delimiter str "," 字符分隔值

支持的操作员：

操作员 行为
> < >= <= 数字比较
== != 平等（适用于任何类型）
contains 字符串列上不区分大小写的子字符串匹配

get_column_distribution

返回特定列的排名频率表——每个值出现的次数以及它代表的行百分比。

参数 类型 默认值 说明
csv_content str 必填 完整的CSV文本内容
column str 必填 要分析的列名
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在数值列中查找具有异常值的行。返回带有列名、值和原因的标记行。

参数 类型 默认值 说明
csv_content str 必填 完整的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文件。可用于检测同一数据集版本之间的变化。

参数 类型 默认值 说明
csv_content_a str 必填 第一个文件的完整CSV文本内容
csv_content_b str 必需 第二个文件的完整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 项目根目录下的文件：

变量 默认值 描述
MAX_ROWS_TO_ANALYZE 500 每个请求处理的最大行数
DEFAULT_OUTPUT_FORMAT markdown 回退输出格式
MAX_PREVIEW_ROWS 10 摘要中的预览行数
NULL_THRESHOLD_WARNING 0.3 零率，超过该值将显示警告
OUTLIER_STDDEV_CUTOFF 3.0 异常检测的Z分数截止值

项目结构

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)

样品数据

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

文件 行 描述
sample_data_usage.csv 40 电信客户使用情况（年龄、计划、数据、流失率）
sample_heart_checks.csv 40 医疗记录（胆固醇、血压、糖尿病、心脏病）
sample_project_revenue.csv 25 故意遗漏值的项目计费

相关 MCP