Pandas MCP服务器

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.10+](https://www.python.org/downloads/) ![Code Style: Black](https://github.com/psf/black) ](https://github.com/marlonluo2018/pandas-mcp-server)

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

](https://github.com/marlonluo2018/pandas-mcp-server/stargazers)

*如果你觉得这个项目有帮助，请考虑给它一个⭐️ star!*

______________________________________________________________________

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

✨ 主要特点

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

🎯 MCP服务器概述

Pandas MCP服务器被设计为 模型上下文协议（MCP）服务器 它为LLM提供了强大的数据处理能力。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 文件以自定义设置，例如：

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

有关详细的配置选项，请参阅配置.md.

步骤4：验证安装

# Test the CLI interface
python cli.py

# Or test the MCP server directly
python server.py

依赖项

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

Claude桌面配置

使用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"]
    }
  }
}

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

视窗：使用正斜杠（推荐）或转义反斜杠

- 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服务器目录的绝对路径。完整路径是必需的，因为Claude Desktop从其自己的工作目录执行命令。

使用Python（传统）

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

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

配置文件位置

视窗: %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：

高价值：具有有限唯一值的类别字段（区域、状态、类别）
高价值：需要解释的代码字段（状态代码“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：侧重于文件结构、数据类型和统计摘要

- 提供对数据集的高级理解 - 提供样本值和基本统计数据 - 帮助LLM了解整体数据架构

interpret_column_data：侧重于具体栏目的详细价值分析

- 显示所有独特值及其频率 - 帮助LLM理解分类数据模式 - 实现更精确的过滤和分组操作 - 在处理多个CSV文件时尤其有价值，因为跨数据集的一致价值理解至关重要

这种两步走的方法确保LLM在生成pandas代码之前对结构和值级别都有理解，从而产生更准确有效的数据分析操作，特别是在处理多个CSV文件时。

🚀 MCP服务器工具

服务器为LLM集成提供了四个主要工具：

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 通过提供对列值的深入见解，使LLM能够生成更精确的过滤、分组和分析操作，特别是在处理需要跨数据集一致理解值的多个CSV文件时。

最佳使用案例：

最有价值：具有有限唯一值的类别字段（区域、状态、类别）
最有价值：需要解释的代码/缩写字段（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]
      ]
    }
  ]
}

主要特点

完整的价值分配：返回所有唯一值及其精确计数
按频率排序：值按出现的降序排列
数据类型分析：标识基础数据类型（对象、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`)

安全功能：

危险操作的黑名单过滤
沙盒执行环境
输出捕获和错误处理
大型结果的内存监控

执行流程：

针对黑名单模式的安全检查
通过编译进行语法验证
在隔离环境中执行代码
结果格式化和内存优化
输出捕获和错误报告

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

内存管理策略

块状加工：以10KB块处理的大文件
类型优化：自动数据类型转换（float64→float32，对象→类别）
有限取样：仅处理元数据的前100行
垃圾收集：重大行动后的强制清理
内存监控：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文件大小限制
黑名单：代码执行的安全限制
CHARTS_DIR：生成图表的目录
日志记录：带轮换的综合测井

安全功能

代码执行沙盒
列入黑名单的操作（文件系统、网络、eval）
内存使用监控
输入验证和净化

📊 图表生成详细信息

HTML图表文件

Pandas MCP服务器生成的所有图表都保存为具有以下特征的独立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

用法

观看：只需双击HTML文件即可在web浏览器中打开它
共享：将HTML文件发送给其他人-不需要额外的软件
嵌入：HTML文件可以嵌入网页或iframe中
印刷：使用浏览器的打印功能将图表另存为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文件

📈 性能优化

内存管理

大文件的分块处理
垃圾回收
内存使用记录
数据集大小限制

文件处理

优化的数据类型推断
字符串列的类别编码
数值数据的浮点32精度
流式CSV读取

🔍 日志记录

原木结构

mcp_server.log：主应用程序日志
记忆_用法：内存消耗跟踪
元数据：文件处理详细信息

日志级别

调试：详细的处理信息
信息：一般操作状态
警告：非关键问题
错误：处理失败

🐛 故障排除

常见问题

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许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

获取帮助

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

常见问题

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

联系方式

电子邮件： marlonluo2018@foxmail.com

______________________________________________________________________

🌟 表示支持

如果你觉得这个项目有用，请考虑给它一个⭐️ GitHub上的明星！您的支持有助于我们：

提高项目可见性
吸引更多用户
激励持续发展
建立更强大的社区

](https://github.com/marlonluo2018/pandas-mcp-server/stargazers)

______________________________________________________________________

📊 项目统计

](https://github.com/marlonluo2018/pandas-mcp-server/issues) ](https://github.com/marlonluo2018/pandas-mcp-server/network) ](https://github.com/marlonluo2018/pandas-mcp-server/stargazers)

______________________________________________________________________

感谢您的支持！请给我们一个⭐️ 如果你觉得这个项目有帮助，请打星！

🔝 返回页首

Pandas MCP Server

快速接入

详细介绍

Pandas MCP服务器

✨ 主要特点

🎯 MCP服务器概述

🛠️ 安装

先决条件

步骤1：克隆存储库

步骤2：安装依赖项

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

步骤4：验证安装

依赖项

Claude桌面配置

使用uvx（推荐）

安装uvx

uvx优势

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

使用Python（传统）

配置文件位置

验证

🔄 工作流程

步骤1：读取文件元数据

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

步骤3：执行Pandas操作

步骤4：生成可视化

如何 interpret_column_data 补足物 read_metadata

🚀 MCP服务器工具

1. read_metadata_tool -文件分析

2. interpret_column_data -列值解释

响应格式

主要特点

3. run_pandas_code_tool -安全代码执行

禁止操作

4. generate_chartjs_tool -交互式可视化

图表输出

🚀 用法

CLI界面（测试与开发）

交互模式

命令行模式

图表输出信息

🔍 代码逻辑与架构

核心组件

1.服务器架构(server.py)

2.元数据处理(core/metadata.py)

3.代码执行(core/execution.py)

4.图表生成(core/visualization.py)

5.栏目释义(core/column_interpretation.py)

6.图表生成器(core/chart_generators/)

数据流架构

内存管理策略

📁 项目结构

🔧 配置

核心配置(core/config.py)

安全功能

📊 图表生成详细信息

HTML图表文件

文件结构

保存位置

用法

模板系统

图表类型

条形图

折线图

饼图

🧪 测试

运行测试

测试数据要求

📈 性能优化

内存管理

文件处理

🔍 日志记录

原木结构

日志级别

🐛 故障排除

常见问题

MCP连接问题

文件未找到

内存问题

图表生成错误

如何 `interpret_column_data` 补足物 `read_metadata`

1. `read_metadata_tool` -文件分析

2. `interpret_column_data` -列值解释

3. `run_pandas_code_tool` -安全代码执行

4. `generate_chartjs_tool` -交互式可视化

1.服务器架构(`server.py`)

2.元数据处理(`core/metadata.py`)

3.代码执行(`core/execution.py`)

4.图表生成(`core/visualization.py`)

5.栏目释义(`core/column_interpretation.py`)

6.图表生成器(`core/chart_generators/`)

核心配置(`core/config.py`)