Pandas MCP Server

Pandas-MCP Server

---

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

✨ 主要功能

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

🎯 MCP 服务概述

Pandas-MCP Server 是一个 模型上下文协议（MCP）服务，旨在为大模型提供强大的数据处理能力。MCP 是一种标准化协议，支持 AI 模型以安全、结构化的方式与外部工具和服务交互。

🛠️ 安装

前置条件

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

步骤 1：克隆仓库

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

步骤 2：安装依赖项

pip install -r requirements.txt

步骤 3：配置环境变量（可选）

服务支持通过环境变量进行广泛配置。复制示例配置文件：

cp .env.example .env

编辑 .env 文件以自定义以下设置：

• 日志级别和文件位置
• 文件大小限制
• 功能开关（启用/禁用图表生成、代码执行）
• 内存监控设置
• 安全黑名单扩展名

详细配置选项请参阅 CONFIGURATION.md。

步骤 4：验证安装

# Test the CLI interface
python cli.py

# Or test the MCP server directly
python server.py

依赖项

• pandas>=2.0.0 - 数据处理与分析
• fastmcp>=1.0.0 - MCP 服务框架
• chardet>=5.0.0 - 字符编码检测
• psutil - 用于内存优化的系统监控

Claude Desktop 配置

使用 uvx（推荐）

uvx 是一款快速的 Python 包安装器和运行器，无需手动设置环境即可轻松运行 Python 工具。

安装 uvx

# Using pip
pip install uv

# Or using pipx (recommended for isolation)
pipx install uv

uvx 的优势

• 无需手动安装：自动下载并运行软件包
• 隔离环境：每次运行都使用干净的虚拟环境
• 快速：使用 uv 的快速依赖解析器
• 固定版本：轻松运行指定版本

将此配置添加到 Claude Desktop 设置中：

{
  "mcpServers": {
    "pandas-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "/path/to/pandas-mcp-server", "pandas-mcp-server"]
    }
  }
}

按操作系统区分的路径格式：

• Windows：使用正斜杠（推荐）或转义后的反斜杠

  • C:/Project/pandas-mcp-server（推荐）
  • C:\\Project\\pandas-mcp-server（转义后的反斜杠）

• macOS/Linux：使用正斜杠

  • /Users/username/projects/pandas-mcp-server
  • /home/username/projects/pandas-mcp-server

注意：将 /path/to/pandas-mcp-server 替换为 pandas-mcp-server 目录的绝对路径。必须使用完整路径，因为 Claude Desktop 会从其自身的工作目录执行命令。

使用 Python（传统方式）

将此配置添加到 Claude Desktop 设置中：

{
  "mcpServers": {
    "pandas-server": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/your/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 服务遵循结构化工作流来进行数据分析和可视化：

步骤 1：读取文件元数据

LLM 调用 read_metadata_tool 以了解文件结构：

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

步骤 2：解释列值（可选）

LLM 调用 interpret_column_data 以了解特定列：

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

何时使用 interpret_column_data：

• 价值高：唯一值有限的分类字段（Region、Status、Category）
• 价值高：需要解释的代码字段（StatusCode“A”、“B”、“C”）
• 价值高：包含缩写或晦涩值的字段
• 价值低：ID 字段（通常唯一值较多且没有明显模式）
• 价值低：电子邮件字段（通常是唯一标识符）
• 价值低：数值型百分比字段（含义通常不言自明）
• 视情况而定：时间字段（适用于非标准格式或分类时间）

步骤 3：执行 Pandas 操作

LLM 根据元数据和列分析结果调用 run_pandas_code_tool：

• 根据已了解的文件结构编写 Pandas 操作
• 执行数据处理、筛选、聚合或分析
• 以 DataFrame、Series 或字典格式接收结果
• 获取经过优化的输出并进行内存管理

步骤 4：生成可视化图表

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

• 将处理后的数据转换为兼容 Chart.js 的格式
• 生成带有自定义控件的交互式 HTML 图表
• 根据数据特征创建柱状图、折线图或饼图
• 输出适用于分析展示的响应式可视化图表

interpret_column_data 如何补充 read_metadata

interpret_column_data 函数旨在补充 read_metadata_tool，深入分析列值：

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

  • 从高层次了解数据集
  • 提供样本值和基本统计信息
  • 帮助大模型理解整体数据架构

• interpret_column_data：侧重于详细分析特定列的值

  • 展示所有唯一值及其频次
  • 帮助大模型理解分类数据模式
  • 支持更精准的筛选和分组操作
  • 在处理多个 CSV 文件时尤其有用，因为此时确保跨数据集对值的理解一致至关重要

这种两步方法可确保大模型在生成 pandas 代码前，既了解数据结构，也了解值的层面，从而实现更准确、更有效的数据分析操作，在处理多个 CSV 文件时尤其如此。

🚀 MCP 服务工具

该服务提供四种主要工具，供大模型集成：

1. read_metadata_tool - 文件分析

从 Excel 和 CSV 文件中提取全面的元数据，包括：

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

用途：向大模型提供数据结构和特征的高层次概览，为数据分析奠定基础。

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，帮助大模型执行更精准的筛选、分组和分析操作；在处理多个 CSV 文件且需要确保跨数据集对值的理解一致时尤其有用。

最佳使用场景：

• 最有价值：唯一值有限的分类字段（Region、Status、Category）
• 最有价值：需要解读的代码/缩写字段（StatusCode “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]
      ]
    }
  ]
}

主要功能

• 完整值分布：返回所有唯一值及其准确计数
• 按频次排序：按出现次数降序排列值
• 数据类型分析：识别底层数据类型（object、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"  // Optional: sheet name or index (default: 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 文件可在任何 Web 浏览器中打开，也便于分享

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 界面（测试与开发）

CLI 提供便捷的命令行界面，无需 MCP 客户端即可测试 MCP 服务功能：

交互模式

# Using Python
python cli.py

# Using uvx
uvx pandas-mcp-cli

启动引导式菜单系统，提供：

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

命令行模式

# Read metadata
python cli.py metadata data.xlsx
uvx pandas-mcp-cli metadata data.xlsx

# Interpret column values (useful for multiple CSV files)
python cli.py interpret data.csv --columns "Region,Status"
uvx pandas-mcp-cli interpret data.csv --columns "Region,Status"

# Execute pandas code
python cli.py execute analysis.py
uvx pandas-mcp-cli execute analysis.py

# Generate charts
python cli.py chart data.json --type bar --title "Sales Analysis"
uvx pandas-mcp-cli chart data.json --type bar --title "Sales Analysis"

图表输出信息

使用 CLI 生成图表时：

• 输出格式：图表会保存为交互式 HTML 文件
• 默认位置：所有图表均保存在 ./charts/ 目录中
• 文件命名：自动使用时间戳和图表类型命名
• 查看图表：在任何 Web 浏览器中打开 HTML 文件，即可查看交互式可视化
• 分享：HTML 文件可轻松分享给他人

🔍 代码逻辑与架构

核心组件

1. 服务架构（server.py）

• FastMCP 集成：使用 FastMCP 框架实现 MCP 协议
• 日志系统：统一日志记录，支持轮转和内存跟踪
• 工具注册：提供四种主要工具，并进行适当的错误处理
• 内存监控：跟踪操作前后的内存使用情况

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

关键逻辑：

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

内存优化：

• 对基数较低的字符串列使用 category dtype
• 将 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：支持线条张力和样式设置的折线图
• PieChartGenerator：支持图例和百分比选项的饼图

数据流架构

User Input → Security Check → Processing → Result → Output
    ↓              ↓            ↓         ↓         ↓
  CLI/MCP → BLACKLIST → Memory Opt → Format → Log/Display

内存管理策略

1. 分块处理：以 10KB 为块处理大型文件
2. 类型优化：自动转换 dtype（float64→float32，object→category）
3. 有限采样：仅处理前 100 行以获取元数据
4. 垃圾回收：主要操作完成后强制清理
5. 内存监控：集成 PSutil 以跟踪内存使用情况

📁 项目结构

pandas-mcp-server/
├── server.py                 # MCP server implementation
├── cli.py                    # CLI interface for testing
├── requirements.txt          # Python dependencies
├── core/                     # Core functionality
│   ├── config.py            # Configuration and constants
│   ├── data_types.py        # Data type utilities
│   ├── metadata.py          # File metadata extraction
│   ├── column_interpretation.py   # Column value analysis
│   ├── execution.py         # Pandas code execution
│   ├── visualization.py     # Chart generation orchestration
│   └── chart_generators/    # Chart-specific implementations
│       ├── __init__.py
│       ├── base.py          # Base chart generator
│       ├── bar.py           # Bar chart generator
│       ├── line.py          # Line chart generator
│       └── pie.py           # Pie chart generator
│       └── templates/       # HTML templates for charts
├── charts/                  # Generated chart files
├── logs/                    # Application logs
├── csv_metadata_format.md   # CSV metadata documentation
└── test_*.py               # Test files

🔧 配置

核心配置（core/config.py）

• MAX_FILE_SIZE：文件大小限制为 100MB
• BLACKLIST：代码执行的安全限制
• CHARTS_DIR：生成图表的目录
• 日志记录：提供轮转功能的全面日志记录

安全特性

• 代码执行沙箱
• 禁止的操作（文件系统、网络、eval）
• 内存使用监控
• 输入验证和清理

📊 图表生成详情

HTML 图表文件

Pandas-MCP Server 生成的所有图表都会保存为独立的 HTML 文件，具有以下特点：

文件结构

• 自包含：每个 HTML 文件都包含所需的 CSS 和 JavaScript
• 交互式：图表包含用于自定义的控件（缩放、筛选等）
• 响应式：图表可适配不同的屏幕尺寸
• 无依赖：HTML 文件无需联网即可离线使用

保存位置

• 默认目录：./charts/（如果目录不存在，会自动创建）
• 配置：可在 core/config.py 中修改 CHARTS_DIR 进行更改
• 文件命名规则：{chart_type}_chart_{timestamp}.html
  • 示例：bar_chart_20250710_143022.html
  • 示例：line_chart_20250710_143547.html

使用方法

1. 查看：双击 HTML 文件即可在 Web 浏览器中打开
2. 共享：将 HTML 文件发送给他人，无需额外软件
3. 嵌入：可将 HTML 文件嵌入网页或 iframe
4. 打印：使用浏览器的打印功能将图表保存为 PDF

模板系统

图表使用 HTML 模板生成，支持：

• 通过 CDN 集成 Chart.js
• 提供用于自定义的交互控件
• 支持移动设备的响应式设计
• 实时调整参数

图表类型

柱状图

• 提供用于调整柱宽和 Y 轴缩放的交互控件
• 支持缩放的响应式设计
• 数据标签和工具提示
• 支持多个数据集

折线图

• 支持多个折线系列
• 可调整折线张力和样式
• 可自定义数据点大小和样式
• 支持阶梯折线选项

饼图

• 可交互式调整环形图中心孔
• 可切换显示百分比或数值
• 可设置图例的位置和样式
• 可控制边框宽度和颜色

🧪 测试

运行测试

# Test metadata extraction
python test_metadata.py

# Test pandas code execution
python test_execution.py

# Test chart generation
python test_generate_barchart.py

# Test all chart types
python test_generate_pyecharts.py

测试数据要求

• 包含多个工作表的 Excel 文件（.xlsx）
• 编码各异的 CSV 文件
• 包含用于生成图表的结构化数据的 JSON 文件

📈 性能优化

内存管理

• 对大型文件进行分块处理
• 自动垃圾回收
• 记录内存使用情况
• 限制数据集大小

文件处理

• 优化 dtype 推断
• 对字符串列进行类别编码
• 数值数据采用 Float32 精度
• 流式读取 CSV

🔍 日志记录

日志结构

• mcp_server.log：主应用日志
• memory_usage：内存消耗跟踪
• metadata：文件处理详情

日志级别

• DEBUG：详细的处理信息
• INFO：常规运行状态
• WARNING：非关键问题
• ERROR：处理失败

🐛 故障排除

常见问题

MCP 连接问题

• 验证 Claude Desktop 配置中的服务路径
• 检查 Python 环境和依赖项
• 确保 server.py 可执行
• 查看 MCP 服务日志中的连接错误

未找到文件

• 确认文件路径为绝对路径
• 检查文件权限
• 确保文件在处理前已存在

内存问题

• 缩小文件或使用分块处理
• 在日志中监控内存使用情况
• 对大型数据集考虑使用数据采样

图表生成错误

• 验证数据结构是否符合预期格式
• 检查是否包含必需的列（字符串列和数值列）
• 确保 Chart.js CDN 可访问

调试模式

通过设置环境变量启用调试日志：

export LOG_LEVEL=DEBUG
python server.py

📄 更多文档

• CSV 元数据格式：参阅 csv_metadata_format.md，了解 CSV 处理的详细文档
• API 文档：查看我们的 API 文档，了解详细使用说明

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

🆘 支持

获取帮助

• 报告问题：在 GitHub 上提交 问题
• 参与讨论：加入我们的 GitHub 讨论

常见问题

查看我们的 FAQ 页面，了解常见问题的解答。

联系方式

• 电子邮件：[email protected]

---

🌟 支持我们

如果您觉得这个项目有用，请考虑在 GitHub 上为它点亮 ⭐️！您的支持有助于我们：

• 提升项目知名度
• 吸引更多用户
• 激励持续开发
• 建设更强大的社区

---

📊 项目统计

---