MCP 服务器

chatExcel

A Model Context Protocol server for intelligent Excel processing and data analysis, offering tools for reading, validating, executing code, and generating interactive visualizations with Excel files.

README

chatExcel - Excel智能处理与数据分析MCP服务器

📋 项目概述

chatExcel 是一个基于 Model Context Protocol (MCP) 的智能 Excel 处理与数据分析服务器，专为复杂 Excel 文件的智能解析、数据处理和可视化设计。提供 14 个专业 MCP 工具，支持智能读取、数据验证、代码执行和交互式图表生成。

🎉 最新更新 (2025-06-10):

✅ 增强多级列头检测系统
✅ 优化参数推荐算法
✅ 完善数据验证功能
✅ 提升缓存性能
✅ 增强安全特性

✨ 核心特性

智能Excel处理: 自动检测编码、多级表头识别、参数推荐
安全代码执行: 沙箱环境支持 pandas/numpy 代码
交互式可视化: 基于 Plotly 的柱状图、饼图、折线图
数据质量验证: 完整性检查、质量评估、批量处理
缓存优化: 智能编码检测缓存，提升性能
复杂格式支持: 处理多级标题、合并单元格、不规则格式

🛠️ MCP工具列表 (14个)

工具名称	功能描述	支持格式
`read_metadata`	CSV 元数据读取与分析	CSV
`read_excel_metadata`	Excel 元数据读取与编码检测	Excel
`suggest_excel_read_parameters_tool`	智能推荐 Excel 读取参数	Excel
`detect_excel_file_structure_tool`	Excel 文件结构检测	Excel
`create_excel_read_template_tool`	生成 Excel 读取代码模板	Excel
`run_excel_code`	Excel 代码执行引擎	Excel
`run_code`	CSV 代码执行引擎	CSV
`bar_chart_to_html`	交互式柱状图生成	数据数组
`pie_chart_to_html`	交互式饼图生成	数据数组
`line_chart_to_html`	交互式折线图生成	数据数组
`verify_data_integrity`	数据完整性验证	Excel, CSV
`validate_data_quality`	数据质量验证与建议	Excel, CSV
`comprehensive_data_verification_tool`	综合数据验证	Excel, CSV
`batch_data_verification_tool`	批量数据验证	Excel, CSV

🚀 编码缓存优化

核心功能

智能缓存: 缓存文件编码检测结果
自动清理: 定期清除过期缓存
大小监控: 实时监控缓存大小
自动备份: 定期备份缓存数据
配置驱动: JSON 配置灵活控制参数

配置文件 (`cache_config.json`)

{
  "cache_settings": {
    "max_cache_size_mb": 10,
    "cache_expiry_days": 7,
    "auto_cleanup_interval": 10,
    "enable_auto_backup": true
  },
  "monitoring": {
    "enable_size_monitoring": true,
    "size_warning_threshold_mb": 8,
    "enable_performance_logging": false,
    "log_level": "INFO"
  },
  "maintenance": {
    "auto_reduce_cache_percentage": 50,
    "enable_startup_cleanup": true,
    "enable_periodic_optimization": true,
    "optimization_frequency": "weekly"
  },
  "paths": {
    "cache_directory": ".encoding_cache",
    "backup_directory": ".encoding_cache",
    "log_file": "cache_maintenance.log"
  }
}

使用方法

命令行工具

# 查看缓存统计
python cache_manager.py stats
# 清理过期缓存
python cache_manager.py cleanup
# 监控缓存大小
python cache_manager.py monitor
# 创建备份
python cache_manager.py backup
# 从备份恢复
python cache_manager.py restore

程序集成

from enhanced_excel_helper import EncodingCache
cache = EncodingCache(config_file="cache_config.json")
encoding = cache.get("/path/to/file.xlsx")
if not encoding:
    detected_encoding = detect_file_encoding("/path/to/file.xlsx")
    cache.set("/path/to/file.xlsx", detected_encoding)

📊 系统要求

Python: 3.11+
操作系统: macOS, Linux, Windows
内存: 建议 4GB+
存储: 至少 500MB

🛠️ 安装部署

快速安装

git clone <repository-url>
cd chatExcel-mcp
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python scripts/health_check.py
python server.py

验证安装

python -c "import pandas as pd; print(f'Pandas {pd.__version__}')"
python -c "import numpy as np; print(f'NumPy {np.__version__}')"
python -c "import plotly; print(f'Plotly {plotly.__version__}')"
python test_complete_functionality.py

🔧 MCP配置

测试配置

cd /path/to/chatExcel-mcp
source venv/bin/activate
python server.py
python -c "import mcp; print('MCP包正常')"

📚 API功能

数据元数据读取

read_metadata: CSV 元数据读取
read_excel_metadata: Excel 元数据读取，支持复杂参数

代码执行

run_code: CSV 数据处理代码执行
run_excel_code: Excel 数据处理代码执行

图表生成

bar_chart_to_html: 交互式柱状图
pie_chart_to_html: 交互式饼图
line_chart_to_html: 交互式折线图

数据质量验证

validate_data_quality: 数据质量分析与建议
comprehensive_data_verification_tool: 综合数据验证
batch_data_verification_tool: 批量数据验证

🧪 测试验证

python test_complete_functionality.py
python test_enhanced_excel.py
python demo_excel_features.py
pytest tests/

🛡️ 安全特性

代码沙箱: 阻止危险操作
资源限制: 100MB 文件大小，30秒执行超时，1GB 内存限制
输入验证: 严格参数检查

🔧 故障排除

常见问题

模块导入失败: 激活虚拟环境，重新安装依赖
文件编码问题: 清理缓存或手动指定编码
MCP服务器启动失败: 检查路径、权限、Python版本

诊断工具

python scripts/health_check.py
python -c "import sys, pandas, numpy, plotly; print(f'Python: {sys.version}, Pandas: {pandas.__version__}, NumPy: {numpy.__version__}, Plotly: {plotly.__version__}')"