# excel_mcp_rust

**Repository Path**: awol2010ex/excel_mcp_rust

## Basic Information

- **Project Name**: excel_mcp_rust
- **Description**: A Model Context Protocol (MCP) server for Excel file manipulation using calamine and rust_xlsxwriter
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel MCP Rust

一个基于 Rust 的 Model Context Protocol (MCP) 服务器，用于 Excel 文件的创建、读取、更新和删除操作。

## 功能特性

### 📊 工作簿管理
- 创建新的 Excel 工作簿
- 打开现有的 Excel 文件
- 保存工作簿到文件
- 关闭工作簿
- 获取工作簿信息
- 设置工作簿属性
- 列出所有工作簿
- 激活工作簿

### 📋 工作表管理
- 创建工作表
- 删除工作表
- 重命名工作表
- 复制工作表
- 移动工作表位置
- 激活工作表
- 列出所有工作表
- 获取工作表信息
- 设置工作表属性
- 设置行高
- 设置列宽

### 🎯 单元格操作
- 设置单元格值
- 获取单元格值
- 设置单元格公式
- 获取单元格公式
- 设置单元格样式
- 获取单元格样式
- 设置单元格注释
- 获取单元格注释
- 设置超链接
- 获取超链接
- 合并/取消合并单元格
- 范围操作（批量读写）

### 🎨 样式管理
- 创建单元格样式
- 应用样式到单元格
- 复制样式
- 删除样式
- 设置默认样式
- 获取默认样式
- 获取单元格样式信息

### 📐 格式设置
- 工作表属性配置

### 🧮 公式处理
- 设置单元格公式
- 获取单元格公式
- 公式解析和计算
- 公式验证

## 技术栈

- **语言**: Rust (2024 edition)
- **Excel 处理**: [calamine](https://crates.io/crates/calamine) (读取), [rust_xlsxwriter](https://crates.io/crates/rust_xlsxwriter) (写入)
- **JSON-RPC**: 自定义实现
- **序列化**: serde, serde_json
- **并发**: Arc + Mutex 线程安全
- **UUID**: 唯一标识符生成

## 快速开始

### 安装依赖

```bash
cargo build --release
```

### 运行服务器

```bash
cargo run --release
```

服务器将在默认端口启动，监听 JSON-RPC 请求。

## API 使用示例

### 创建工作簿

```json
{
  "jsonrpc": "2.0",
  "method": "create_workbook",
  "params": {
    "name": "MyWorkbook"
  },
  "id": 1
}
```

### 创建工作表

```json
{
  "jsonrpc": "2.0",
  "method": "create_worksheet",
  "params": {
    "workbook_id": "workbook_uuid",
    "name": "Sheet1"
  },
  "id": 2
}
```

### 设置单元格值

```json
{
  "jsonrpc": "2.0",
  "method": "set_cell_value",
  "params": {
    "workbook_id": "workbook_uuid",
    "worksheet_name": "Sheet1",
    "cell_reference": "A1",
    "value": "Hello Excel!"
  },
  "id": 3
}
```

### 设置单元格公式

```json
{
  "jsonrpc": "2.0",
  "method": "set_cell_formula",
  "params": {
    "workbook_id": "workbook_uuid",
    "worksheet_name": "Sheet1",
    "cell_reference": "A2",
    "formula": "=SUM(B1:C1)"
  },
  "id": 4
}
```

### 创建样式

```json
{
  "jsonrpc": "2.0",
  "method": "create_cell_style",
  "params": {
    "workbook_id": "workbook_uuid",
    "style_name": "MyStyle",
    "font": {
      "name": "Arial",
      "size": 12,
      "bold": true,
      "color": "#FF0000"
    },
    "background_color": "#FFFF00",
    "alignment": {
      "horizontal": "center",
      "vertical": "center"
    }
  },
  "id": 5
}
```

### 应用样式到单元格

```json
{
  "jsonrpc": "2.0",
  "method": "apply_cell_style",
  "params": {
    "workbook_id": "workbook_uuid",
    "worksheet_name": "Sheet1",
    "cell_reference": "A1",
    "style_id": "style_uuid"
  },
  "id": 6
}
```

### 范围操作

```json
{
  "jsonrpc": "2.0",
  "method": "set_range_values",
  "params": {
    "workbook_id": "workbook_uuid",
    "worksheet_name": "Sheet1",
    "start_cell": "A1",
    "end_cell": "C3",
    "values": [
      ["Name", "Age", "City"],
      ["Alice", 25, "New York"],
      ["Bob", 30, "London"]
    ]
  },
  "id": 7
}
```

## 项目结构

```
excel_mcp_rust/
├── src/
│   ├── core.rs              # ExcelServer 核心实现
│   ├── handlers.rs          # JSON-RPC 请求处理器
│   ├── main.rs              # 服务器入口点
│   ├── lib.rs               # 库导出
│   └── tools/               # 功能模块
│       ├── mod.rs            # 模块定义
│       ├── workbook.rs       # 工作簿操作
│       ├── worksheet.rs      # 工作表操作
│       ├── cell.rs           # 单元格操作
│       ├── style.rs          # 样式管理
│       ├── formula.rs        # 公式处理
│       └── management.rs     # 管理工具
├── tests/
│   └── integration_tests.rs  # 集成测试
├── Cargo.toml               # 项目配置
└── README.md               # 项目文档
```

## 核心特性

### 线程安全
使用 `Arc<Mutex<ExcelServer>>` 确保多线程环境下的安全访问。

### 错误处理
完善的错误处理机制，所有操作返回 `Result<Value, String>`。

### 数据验证
输入参数验证，确保数据完整性和有效性。

### 灵活的范围操作
支持多种范围表示方式：
- 范围字符串："A1:B2"
- 起始和结束单元格：start_cell + end_cell

### 样式系统
完整的样式支持：
- 字体样式（名称、大小、颜色、粗体、斜体、下划线）
- 背景颜色
- 边框样式
- 对齐方式
- 文本换行

### 参数兼容性
- 支持 `worksheet_id` 和 `worksheet_name` 两种参数格式
- 支持 `cell_reference` 和 `cell_address` 两种参数格式
- 自动参数验证和错误提示

## 在 Trae 中安装配置

### 1. 构建 Excel MCP 服务器

首先确保项目已正确构建：

```bash
cd e:\workspace_rust\excel_mcp_rust
cargo build --release
```

### 2. 配置 Trae settings.json

在 Trae 的 `settings.json` 文件中添加 MCP 服务器配置：

```json
{
  "mcpServers": {
      "excel": {
        "command": "e:\\workspace_rust\\excel_mcp_rust\\target\\release\\excel_mcp_rust.exe"
      }
  }
  
}
```

### 3. 配置参数说明

- **command**: Excel MCP 服务器可执行文件路径
- **args**: 启动参数（可选）
- **env**: 环境变量（可选）
- **disabled**: 是否禁用此服务器
- **timeout**: 超时时间（毫秒）


### 4. 使用示例

配置完成后，在 Trae 中可以使用自然语言操作 Excel：

- "创建一个名为 '销售报表' 的 Excel 文件"
- "在 A1 单元格写入 '产品名称'"
- "设置 B2:C5 范围的值为 [[1,2],[3,4],[5,6]]"
- "保存工作簿到桌面"

### 5. 故障排除

如果服务器无法连接：

1. **检查路径**: 确保 command 路径正确指向 exe 文件
2. **检查构建**: 确认 `cargo build --release` 成功完成
3. **查看日志**: Trae 的 MCP 面板会显示连接错误信息
4. **手动测试**: 先手动运行 `excel_mcp_rust.exe` 验证能否启动

## 测试

项目包含全面的测试套件：

```bash
# 运行所有测试
cargo test

# 运行特定测试
cargo test test_workbook_creation

# 带输出运行测试
cargo test -- --nocapture
```

## 开发状态

✅ **已完成**: 所有核心功能实现和测试通过
- 工作簿管理 (8/8 测试通过)
- 工作表管理 (8/8 测试通过)  
- 单元格操作 (8/8 测试通过)
- 样式管理 (6/6 测试通过)
- 公式处理 (4/4 测试通过)
- 集成测试 (10/10 测试通过)
- 单元测试 (17/17 测试通过)

## 依赖版本

所有依赖项使用精确版本锁定，确保构建一致性：

- serde = "=1.0.228"
- serde_json = "=1.0.145"
- calamine = "=0.26.1"
- rust_xlsxwriter = "=0.84.1"
- anyhow = "=1.0.100"
- chrono = "=0.4.42"
- uuid = "=1.19.0"

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 许可证

Apache-2.0 License

## 作者

awol2005ex <awol2005ex@163.com>