Excel MCP Rust

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

功能特性

📊 工作簿管理

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

📋 工作表管理

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

🎯 单元格操作

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

🎨 样式管理

• 创建单元格样式
• 应用样式到单元格
• 复制样式
• 删除样式
• 设置默认样式
• 获取默认样式
• 获取单元格样式信息

📐 格式设置

• 工作表属性配置

🧮 公式处理

• 设置单元格公式
• 获取单元格公式
• 公式解析和计算
• 公式验证

技术栈

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

快速开始

安装依赖

cargo build --release

运行服务器

cargo run --release

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

API 使用示例

创建工作簿

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

创建工作表

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

设置单元格值

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

设置单元格公式

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

创建样式

{
  "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
}

应用样式到单元格

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

范围操作

{
  "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 服务器

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

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

2. 配置 Trae settings.json

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

{
  "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 验证能否启动

测试

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

# 运行所有测试
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