STARWARCLOUD STARWAR.AI
返回市场
excel-mcp-服务器

excel-mcp-服务器

作者：marlonluo201819 星标更新：2025-11-14
安装使用来源：spider==github.com

项目介绍

Pandas-MCP 服务器

MIT 许可证 Python 3.8+ 代码风格：Black GitHub stars

<div align="center">

🚀 强大的AI驱动数据分析工具 - 通过MCP协议，使LLMs能够安全高效地执行pandas代码并生成可视化图表

GitHub stars

如果您发现这个项目有用，请考虑给它一个⭐️星！

</div>

一个全面的模型上下文协议（MCP）服务器，使LLMs能够通过标准化的工作流程执行pandas代码进行数据分析和可视化。

✨ 主要特性

  • 🔒 安全执行环境 - 沙箱代码执行防止恶意操作并保护系统安全
  • 📊 智能数据分析 - 自动提取文件元数据，理解数据结构，并提供智能分析建议
  • 🎨 交互式可视化 - 一键生成各种交互图表，并实时调整参数
  • 🧠 内存优化 - 智能内存管理支持大型文件处理，并自动优化数据类型
  • 🔧 易于集成 - 简单配置即可无缝集成到如Claude Desktop这样的AI助手中
  • 📝 命令行支持 - 提供命令行界面方便测试和开发

🎯 MCP服务器概述

Pandas-MCP服务器设计为一个模型上下文协议（MCP）服务器，为LLMs提供强大的数据处理能力。MCP是一个标准化协议，允许AI模型以安全、结构化的方式与外部工具和服务进行交互。

🛠️ 安装

预备条件

  • Python 3.8+
  • pip 包管理器
  • Git（用于克隆仓库）

第一步：克隆仓库

git clone https://github.com/marlonluo2018/pandas-mcp-server.git
cd pandas-mcp-server

第二步：安装依赖

pip install -r requirements.txt

第三步：验证安装

# 测试CLI接口
python cli.py

# 或直接测试MCP服务器
python server.py

依赖项

  • pandas>=2.0.0 - 数据操作和分析
  • fastmcp>=1.0.0 - MCP服务器框架
  • chardet>=5.0.0 - 字符编码检测
  • psutil - 系统监控以优化内存

Claude Desktop配置

在您的Claude Desktop设置中添加以下配置：

{
  "mcpServers": {
    "pandas-server": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/your/pandas-mcp-server/server.py"]
    }
  }
}

注意：用您实际克隆仓库的位置替换/path/to/your/pandas-mcp-server/server.py。

示例路径：

  • Windows: "C:\\Users\\YourName\\pandas-mcp-server\\server.py"
  • macOS/Linux: "/home/username/pandas-mcp-server/server.py"

配置文件位置

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

验证

配置完成后，重启Claude Desktop。服务器应该出现在MCP工具列表中，有四个可用工具：

  • read_metadata_tool - 文件分析
  • interpret_column_data - 列值解释
  • run_pandas_code_tool - 代码执行
  • generate_chartjs_tool - 图表生成

🔄 工作流

Pandas MCP服务器遵循一个结构化的数据分析和可视化工作流：

第一步：读取文件元数据

**LLM调用read_metadata_tool**来了解文件结构：

  • 提取文件类型、大小、编码和列信息
  • 获取数据类型、样本值和统计摘要
  • 接收数据质量警告和建议的操作
  • 在处理之前理解数据集结构

第二步：解释列值（可选）

**LLM调用interpret_column_data**来理解特定列：

  • 从重要列中提取所有唯一值
  • 识别分类数据中的模式
  • 理解代码或缩写的含义
  • 主要目的：通过提供对列值的深入理解来补充元数据，这有助于LLM在下一步生成更准确有效的pandas代码，特别是在处理多个CSV文件时

何时使用interpret_column_data：

  • 高价值：具有有限唯一值的分类字段（地区、状态、类别）
  • 高价值：需要解释的代码字段（状态码“A”、“B”、“C”）
  • 高价值：带有缩写或隐晦值的字段
  • 低价值：ID字段（通常唯一值且无模式）
  • 低价值：电子邮件字段（通常是唯一标识符）
  • 低价值：数字百分比字段（已经自解释）
  • 有条件：时间字段（对于非标准格式或分类时间有用）

第三步：执行Pandas操作

LLM基于元数据和列分析调用run_pandas_code_tool：

  • 使用理解的文件结构制定pandas操作
  • 执行数据处理、过滤、聚合或分析
  • 以DataFrame、Series或字典格式接收结果
  • 获得经过内存管理优化的输出

第四步：生成可视化图表

**LLM调用generate_chartjs_tool**来创建交互图表：

  • 将处理过的数据转换为Chart.js兼容格式
  • 生成带有定制控制的交互HTML图表
  • 根据数据特征创建条形图、折线图或饼图
  • 输出响应式可视化图表以供分析展示

如何interpret_column_data补充read_metadata

interpret_column_data函数旨在通过提供对列值的深入理解来补充read_metadata_tool：

  • read_metadata_tool：专注于文件结构、数据类型和统计摘要

    • 提供数据集的高层次理解
    • 提供样本值和基本统计信息
    • 帮助LLM理解整体数据架构

  • interpret_column_data：专注于特定列的详细值分析

    • 揭示所有唯一值及其频率
    • 帮助LLM理解分类数据模式
    • 使更精确的过滤和分组操作成为可能
    • 特别有价值的是在处理多个CSV文件时，其中跨数据集的一致值理解至关重要

这种两步方法确保了LLM在生成pandas代码之前既具备结构又具备值级的理解，从而实现更准确有效的数据分析操作，尤其是在处理多个CSV文件时。

🚀 MCP服务器工具

服务器暴露四个主要工具供LLM集成：

1. read_metadata_tool - 文件分析

从Excel和CSV文件中提取综合元数据包括：

  • 文件类型、大小、编码和结构
  • 列名、数据类型和样本值
  • 统计摘要（空值数、唯一值数、最小/最大/平均值）
  • 数据质量警告和建议的操作
  • 大文件的内存优化处理

目的：为LLM提供数据结构和特性的高层次理解，作为数据分析的基础。

MCP工具使用：

{
  "tool": "read_metadata_tool",
  "args": {
    "file_path": "/path/to/sales_data.xlsx"
  }
}

2. interpret_column_data - 列值解释

解释特定列以理解其值模式：

  • 从指定列中提取所有唯一值及其计数
  • 支持单个或多个列解释
  • 常见数据类型的自动模式识别
  • 完整值分布无需采样
  • 支持CSV（.csv）和Excel（.xlsx, .xls）文件
  • Excel工作表选择能力

目的：通过提供对列值的深入理解来补充read_metadata_tool，使LLM能够生成更精确的过滤、分组和分析操作，特别是在处理需要跨数据集一致值理解的多个CSV文件时。

最佳使用案例：

  • 最有价值：具有有限唯一值的分类字段（地区、状态、类别）
  • 最有价值：需要解释的代码/缩写字段（状态码“A”、“B”、“C”）
  • 较少价值：ID字段、电子邮件字段或数字百分比字段
  • 情境相关：时间字段（对于非标准格式有用）

响应格式

该函数返回以下格式的结构化响应：

{
  "columns_interpretation": [
    {
      "column_name": "Region",
      "data_type": "object",
      "total_values": 1000,
      "null_count": 5,
      "unique_count": 4,
      "unique_values_with_counts": [
        ["North", 350],
        ["South", 280],
        ["East", 220],
        ["West", 145]
      ]
    }
  ]
}

关键特性

  • 完整值分布：返回所有唯一值及其确切计数
  • 按频率排序：值按出现频率降序排列
  • 数据类型分析：识别底层数据类型（对象、int64等）
  • 质量指标：提供空值数和总值数以评估数据质量
  • 多列支持：可以在单个请求中分析多个列

MCP工具使用：

{
  "tool": "interpret_column_data",
  "args": {
    "file_path": "/path/to/sales_data.csv",
    "column_names": ["Region", "Status"]
  }
}

Excel文件使用（可选工作表选择）：

{
  "tool": "interpret_column_data",
  "args": {
    "file_path": "/path/to/sales_data.xlsx",
    "column_names": ["Region", "Status"],
    "sheet_name": "Q3_Sales"  // 可选：工作表名称或索引（默认：0）
  }
}

3. run_pandas_code_tool - 安全代码执行

执行pandas操作：

  • 对抗恶意代码的安全过滤
  • 大数据集的内存优化
  • 全面的错误处理和调试
  • 支持DataFrame、Series和字典结果

目的：利用来自read_metadata_tool和interpret_column_data的见解来执行精确的数据分析操作，特别有价值的是在处理具有一致值模式的多个CSV文件时。

禁止操作

出于安全原因，以下操作被阻止：

  • 系统访问：os., sys., subprocess. - 防止文件系统和系统访问
  • 代码执行：open(), exec(), eval() - 阻止动态代码执行
  • 危险导入：import os, import sys - 防止特定有害导入
  • 浏览器/DOM访问：document., window., XMLHttpRequest - 阻止浏览器操作
  • JavaScript/远程：fetch(), eval(), Function() - 阻止远程代码执行
  • 脚本注入：script, javascript: - 阻止脚本注入尝试

要求：

  • 最终结果必须分配给result变量
  • 代码应包含必要的导入（pandas可用为pd）
  • 所有代码在执行前都会经过安全过滤

MCP工具使用：

{
  "tool": "run_pandas_code_tool",
  "args": {
    "code": "import pandas as pd\ndf = pd.read_excel('/path/to/data.xlsx')\nresult = df.groupby('Region')['Sales'].sum()"
  }
}

4. generate_chartjs_tool - 交互式可视化

使用Chart.js生成交互图表：

  • 条形图 - 用于分类比较
  • 折线图 - 用于趋势分析
  • 饼图 - 用于比例数据
  • 带有定制控制的交互HTML模板

图表输出

  • 文件格式：所有图表都生成为独立的HTML文件
  • 保存位置：默认情况下图表保存在./charts/目录中
  • 文件命名：文件自动命名为时间戳和图表类型（例如，bar_chart_20250710_143022.html）
  • 可访问性：HTML文件可以在任何网络浏览器中打开并轻松共享

MCP工具使用：

{
  "tool": "generate_chartjs_tool",
  "args": {
    "data": {
      "columns": [
        {
          "name": "Region",
          "type": "string",
          "examples": ["North", "South", "East", "West"]
        },
        {
          "name": "Sales",
          "type": "number",
          "examples": [15000, 12000, 18000, 9000]
        }
      ]
    },
    "chart_types": ["bar"],
    "title": "Sales by Region"
  }
}

🚀 使用

命令行界面（测试和开发）

cli.py提供了方便的命令行界面，无需MCP客户端即可测试MCP服务器的功能：

交互模式

python cli.py

启动一个引导菜单系统，包括：

  • 分步骤工作流指导
  • 自动输入验证
  • 清晰的错误消息
  • 支持带空格的文件路径

命令行模式

# 读取元数据
python cli.py metadata data.xlsx

# 解释列值（适用于多个CSV文件）
python cli.py interpret data.csv --columns "Region,Status"

# 执行pandas代码
python cli.py execute analysis.py

# 生成图表
python cli.py chart data.json --type bar --title "Sales Analysis"

图表输出信息

使用CLI生成图表时：

  • 输出格式：图表保存为交互HTML文件
  • 默认位置：所有图表默认保存在./charts/目录中
  • 文件命名：自动命名带有时间戳和图表类型的文件
  • 查看图表：在任何网络浏览器中打开HTML文件以查看交互可视化
  • 共享：HTML文件可以轻松与其他用户共享

🔍 代码逻辑与架构

核心组件

1. 服务器架构（server.py）

  • FastMCP集成：使用FastMCP框架实现MCP协议
  • 日志系统：统一的日志记录，带有旋转和内存跟踪
  • 工具注册：暴露四个主要工具，并带有适当的错误处理
  • 内存监控：跟踪操作前后内存使用情况

2. 元数据处理（core/metadata.py）

关键逻辑：

  • 文件验证（存在性、大小限制）
  • CSV文件的编码检测
  • 内存优化的数据处理（100行样本）
  • 综合统计分析
  • 数据质量评估和警告

内存优化：

  • 对于低基数字符串列使用category数据类型
  • 将float64转换为float32以提高内存效率
  • 仅处理前100行以提取元数据
  • 处理后强制垃圾回收

3. 代码执行（core/execution.py）

安全特性：

  • 对黑名单模式的安全检查
  • 沙箱执行环境
  • 输出捕获和错误处理
  • 大结果的内存监控

执行流程：

  1. 对BLACKLIST模式进行安全检查
  2. 通过编译进行语法验证
  3. 在隔离环境中执行代码
  4. 结果格式化和内存优化
  5. 输出捕获和错误报告

4. 图表生成（core/visualization.py）

架构：

  • 基于模板的HTML生成
  • 通过CDN集成Chart.js
  • 交互控件以进行定制
  • 自动文件命名和组织

图表类型：

  • 条形图：分类数据，带有条形宽度和Y轴控制
  • 折线图：趋势分析，带有线条样式选项
  • 饼图：比例数据，带有甜甜圈孔和百分比显示

5. 列解释（core/column_interpretation.py）

功能：

  • 对指定列的完整值分布分析
  • 提取唯一值及其确切计数
  • 数据类型识别和质量指标
  • 单个请求中处理多列
  • 特别有价值的是在处理多个CSV文件时，确保跨数据集的一致值理解

关键特性：

  • 按频率排序（降序）
  • 空值检测和报告
  • 大数据集的内存优化处理
  • 支持分类和数值数据
  • 使跨多个CSV文件的数据分析保持一致

6. 图表生成器（core/chart_generators/）

基类（base.py）：

  • 所有图表生成器的抽象基类
  • 模板管理和文件I/O
  • 常用图表配置

具体生成器：

  • BarChartGenerator：带有交互控件的条形图
  • LineChartGenerator：带有张力和样式的折线图