Excel MCP Server

🚀 基于Model Context Protocol (MCP)的Excel处理服务器，使AI助手能够读取、写入和操作Excel文件。

✨ 功能特性

• 📊 Excel文件操作: 支持读取、写入和创建Excel文件 (.xlsx, .xls, .csv)
• 🔍 数据查询: 高级数据查询和筛选功能
• ✏️ 单元格操作: 数据修改和格式设置
• 📋 工作表管理: 创建、删除、重命名工作表
• 🧮 公式计算: 支持Excel公式的应用和计算
• 📈 基础图表: 图表创建和操作
• 🛡️ 安全机制: 路径验证、文件大小限制、自动备份
• 🎨 数据格式化: 丰富的单元格格式设置选项

🏗️ 系统架构

graph TB
    subgraph "AI客户端"
        A[Claude Desktop/Code]
        B[MCP客户端]
    end
    
    subgraph "Excel MCP服务器"
        C[FastMCP服务器]
        D[Excel工具处理器]
        E[文件管理器]
        F[数据处理器]
        G[安全验证器]
    end
    
    subgraph "本地文件系统"
        H[Excel文件]
        I[临时文件]
        J[日志文件]
    end
    
    A --> B
    B <--> C
    C --> D
    D --> E
    D --> F
    D --> G
    E <--> H
    F <--> I
    G --> J

🚀 快速开始

1. 环境要求

• Python 3.10 或更高版本
• pip 包管理器

2. 安装依赖

git clone https://github.com/YOUR_USERNAME/excel-mcp.git
cd excel-mcp
pip install -r requirements.txt

3. 启动服务器

python server.py

4. 配置Claude Desktop

在Claude Desktop的配置文件中添加以下配置：

{
  "mcpServers": {
    "excel-mcp": {
      "command": "python",
      "args": ["/path/to/excel-mcp/server.py"],
      "env": {
        "EXCEL_MCP_CONFIG": "/path/to/excel-mcp/config.json"
      }
    }
  }
}

🛠️ 支持的操作

📁 文件操作

• read_excel_file - 读取Excel文件内容
• write_excel_file - 写入数据到Excel文件
• create_excel_file - 创建新的Excel文件
• get_excel_info - 获取Excel文件信息

📊 数据操作

• query_excel_data - 查询Excel数据
• get_range_info - 获取单元格范围信息
• apply_formula - 应用Excel公式

📋 工作表操作

• list_worksheets - 列出所有工作表
• create_worksheet - 创建新工作表
• delete_worksheet - 删除工作表
• rename_worksheet - 重命名工作表

💡 使用示例

读取Excel文件

请帮我读取文件 data/sales_data.xlsx 的内容

创建新文件

创建一个新的Excel文件 report.xlsx，包含两个工作表：Sales 和 Summary

数据查询

在 sales_data.xlsx 的 Sheet1 中查找所有销售额大于1000的记录

应用公式

在 report.xlsx 的 Sales 工作表的D2单元格中应用公式 =B2*C2

🔧 配置选项

服务器配置通过 config.json 文件管理：

{
  "server": {
    "name": "excel-mcp",
    "version": "1.0.0"
  },
  "excel": {
    "max_file_size": "100MB",
    "supported_formats": [".xlsx", ".xls", ".csv"],
    "backup_enabled": true
  },
  "security": {
    "allowed_paths": ["./data", "~/Documents", "~/Desktop"],
    "max_memory_usage": "512MB"
  }
}

🧪 测试

运行测试套件：

# 基础功能测试
python tests/test_excel_mcp.py

# 快速功能测试
python test_quick.py

📁 项目结构

excel-mcp/
├── src/excel_mcp/          # 核心源码
│   ├── server.py           # MCP服务器主程序
│   ├── file_manager.py     # 文件管理模块
│   ├── data_processor.py   # 数据处理模块
│   ├── sheet_operations.py # 工作表操作模块
│   ├── security.py         # 安全验证模块
│   └── config.py           # 配置管理模块
├── tests/                  # 测试文件
├── data/                   # 示例数据
├── docs/                   # 文档
└── config.json             # 配置文件

🛡️ 安全特性

• 路径验证: 防止目录遍历攻击
• 文件类型检查: 仅允许指定的Excel格式
• 文件大小限制: 防止内存耗尽
• 访问权限控制: 限制可访问的目录
• 自动备份: 修改文件前自动创建备份
• 详细日志: 完整的操作和错误日志

🤝 贡献指南

我们欢迎所有形式的贡献！请查看 贡献指南 了解详情。

开发环境设置

1. Fork 这个仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📄 许可证

这个项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Model Context Protocol - 提供了优秀的MCP协议
• openpyxl - 强大的Excel文件处理库
• pandas - 数据分析和处理工具

📞 支持

如果你遇到任何问题或有疑问，请：

1. 查看 FAQ
2. 搜索现有的 Issues
3. 创建新的 Issue

---

⭐ 如果这个项目对你有帮助，请给它一个星标！