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配置
推荐配置 (mcp_config_flexible.json
)
{
"mcpServers": {
"chatExcel": {
"command": "python3",
"args": ["server.py"],
"cwd": "/path/to/chatExcel-mcp",
"env": {
"PATH": "/path/to/venv/bin:/usr/local/bin:/usr/bin:/bin",
"VIRTUAL_ENV": "/path/to/venv",
"PYTHONPATH": "/path/to/chatExcel-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__}')"
📄 许可证
MIT 许可证,详见 LICENSE。
🤝 贡献指南
- Fork 仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature
) - 提交更改 (
git commit -m 'Add some AmazingFeature'
) - 推送分支 (
git push origin feature/AmazingFeature
) - 开启 Pull Request
📞 联系方式
- 项目主页: GitHub Repository
- 问题反馈: Issues
- 文档: Wiki
chatExcel - 智能高效的 Excel 数据处理! 🚀