# Excel MCP Server

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

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-1.2.0+-green.svg)](https://github.com/modelcontextprotocol)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](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)

---

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