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文件的完整统计分析。返回每列摘要，包括类型、空率、唯一计数和特定于类型的统计信息。

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表返回。可用于在运行完整分析之前检查结构和值。不进行清洁。

输出示例：

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

______________________________________________________________________

filter_csv

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

______________________________________________________________________

get_column_distribution

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

输出示例：

[
  {"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在数值列中查找具有异常值的行。返回带有列名、值和原因的标记行。

方法：

• 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文件。可用于检测同一数据集版本之间的变化。

输出示例(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 项目根目录下的文件：

______________________________________________________________________

项目结构

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/ 用于测试：

______________________________________________________________________