README.md•5.72 kB
# Excel MCP Server
> 🚀 基于Model Context Protocol (MCP)的Excel处理服务器，使AI助手能够读取、写入和操作Excel文件。
[](https://python.org)
[](https://github.com/modelcontextprotocol)
[](https://opensource.org/licenses/MIT)
## ✨ 功能特性
- 📊 **Excel文件操作**: 支持读取、写入和创建Excel文件 (.xlsx, .xls, .csv)
- 🔍 **数据查询**: 高级数据查询和筛选功能
- ✏️ **单元格操作**: 数据修改和格式设置
- 📋 **工作表管理**: 创建、删除、重命名工作表
- 🧮 **公式计算**: 支持Excel公式的应用和计算
- 📈 **基础图表**: 图表创建和操作
- 🛡️ **安全机制**: 路径验证、文件大小限制、自动备份
- 🎨 **数据格式化**: 丰富的单元格格式设置选项
## 🏗️ 系统架构
```mermaid
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. 安装依赖
```bash
git clone https://github.com/YOUR_USERNAME/excel-mcp.git
cd excel-mcp
pip install -r requirements.txt
```
### 3. 启动服务器
```bash
python server.py
```
### 4. 配置Claude Desktop
在Claude Desktop的配置文件中添加以下配置：
```json
{
"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` 文件管理：
```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"
}
}
```
## 🧪 测试
运行测试套件：
```bash
# 基础功能测试
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格式
- **文件大小限制**: 防止内存耗尽
- **访问权限控制**: 限制可访问的目录
- **自动备份**: 修改文件前自动创建备份
- **详细日志**: 完整的操作和错误日志
## 🤝 贡献指南
我们欢迎所有形式的贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解详情。
### 开发环境设置
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](LICENSE) 文件了解详情。
## 🙏 致谢
- [Model Context Protocol](https://github.com/modelcontextprotocol) - 提供了优秀的MCP协议
- [openpyxl](https://openpyxl.readthedocs.io/) - 强大的Excel文件处理库
- [pandas](https://pandas.pydata.org/) - 数据分析和处理工具
## 📞 支持
如果你遇到任何问题或有疑问，请：
1. 查看 [FAQ](docs/FAQ.md)
2. 搜索现有的 [Issues](https://github.com/YOUR_USERNAME/excel-mcp/issues)
3. 创建新的 [Issue](https://github.com/YOUR_USERNAME/excel-mcp/issues/new)
---
⭐ 如果这个项目对你有帮助，请给它一个星标！