ExcelForge

基于 MCP 协议的 Excel 自动化工具服务。单一 Host 入口，通过 Profile / Bundle 按场景装配工具。

当前版本 v2.5.0 — 18 个能力域 · 101+ 个工具 · 14 个 Bundle · 12 个 Profile（含 5 个开发 Profile）。

安装

前置要求

项目	要求
Python	≥ 3.11
操作系统	Windows（需要 Excel COM 自动化）
Excel	Windows 版 Microsoft Excel
包管理	uv

第一步：安装 uv（如尚未安装）

pip install uv

第二步：克隆仓库

git clone <你的仓库地址>
cd ExcelForge

第三步：安装依赖

uv sync

依赖说明：uv sync 会自动从 pyproject.toml 安装以下依赖包：

• pydantic >= 2.8
• PyYAML >= 6.0.1
• mcp >= 1.2.0
• pywin32 >= 306 (Windows)
• psutil >= 5.9.0
• openpyxl >= 3.1.5

第四步：快速验证

# 查看可用 Profile
uv run python -m excelforge.gateway.host --config excel-mcp.yaml --list-profiles

# 查看可用 Bundle
uv run python -m excelforge.gateway.host --config excel-mcp.yaml --list-bundles

# 查看当前 Profile 的工具清单
uv run python -m excelforge.gateway.host --config excel-mcp.yaml --profile basic_edit --dump-tools

配置文件说明

本项目使用两个配置文件，一般不需要修改：

文件	作用	是否需要修改
excel-mcp.yaml	Gateway 入口配置，定义服务端口、超时等	一般不需要
runtime-config.yaml	Excel 运行时配置，定义 Excel 行为、路径限制等	按需调整

两个文件都使用相对路径，确保从项目根目录运行命令即可正常工作。

启动

uv run python -m excelforge.gateway.host --config excel-mcp.yaml --profile basic_edit

如何选择 Profile

Profile 决定暴露哪些工具，根据使用场景选择：

场景	推荐 Profile	说明
基础读写操作	basic_edit	打开/读写/Sheet 管理
需要公式和格式	calc_format	基础 + 公式 + 格式
VBA 自动化	automation	VBA + 快照/备份/回滚
数据分析	data_workflow	PQ 查询 + Table + 分析
不确定用什么	basic_edit	最安全的选择

切换 Profile：修改 --profile 参数后重启服务。

选择 Profile

Profile 决定暴露哪些工具。按场景选，不确定就从 basic_edit 开始。

Profile	做什么	工具数
basic_edit	打开 / 读写 / Sheet 管理	35
calc_format	上述 + 公式 + 格式	46
automation	VBA + 快照 / 备份 / 回滚	40
data_workflow	PQ 查询 + Table + 分析审计 + workbook_ops	33
reporting	导出 PDF / CSV + 分析	32
artifact_extract	Package 直接解析（无需 Excel COM）	16
artifact_transform	artifact_extract + patch / merge / compare	22
batch_delivery	artifact_transform + 批量处理	26
all	全部工具（仅 CLI / 回归测试）	101+

开发 Profile（推荐 AI 编程使用）：

Profile	做什么	工具数
artifact_first	Package 优先，COM 兜底	42
package_first	批量处理优先	48
batch_first	批量操作优先	50
chart_first	图表操作优先	44
rules_first	条件格式优先	42

切换方法：改 --profile 参数，重启服务。

微调 Bundle

Profile 不完全匹配时，用 --enable-bundle / --disable-bundle 加减：

# data_workflow + 结构编辑
--profile data_workflow --enable-bundle edit_structure  # 33 + 6 = 39

# 基础编辑 + 结构编辑
--profile basic_edit --enable-bundle edit_structure  # 35 + 6 = 41

可用 Bundle：

Bundle	工具数	内容
foundation	8	服务状态 + 工作簿 I/O（必选）
data	8	Table 管理
analysis	6	结构扫描 / 公式审计 / 分析报告
workbook_ops	6	另存 / 刷新 / 计算 / 导出 PDF·CSV
edit_basic	7	Sheet 创建/重命名 + Range 读写/复制
edit_structure	6	Sheet 复制/移动/隐藏 + Range 查找替换/自动调整
calc_format	11	公式 + 格式
automation	8	VBA
recovery	8	快照 / 回滚 / 备份
artifact_export	8	Package XML 解析（无需 Excel COM）
artifact_patch	7	Package 补丁 / 替换 / 合并 / 比较
batch_ops	3	批量提取 / 变换 / 比较
chart_operations	4	图表列表 / 详情 / 系列 / 导出
format_rules	4	条件格式规则应用 / 更新 / 复制 / 清除

常用命令

# 查看可用 Profile / Bundle
--list-profiles
--list-bundles

# 诊断当前 Profile 的工具清单
--dump-tools
--dump-tools-with-index

# 查看 Profile 解析过程
--dump-profile-resolution

完整示例：

uv run python -m excelforge.gateway.host --config excel-mcp.yaml --profile basic_edit --dump-tools

MCP 客户端配置

{
  "mcpServers": {
    "excel": {
      "command": "uv",
      "args": [
        "run", "python", "-m", "excelforge.gateway.host",
        "--config", "YOUR_PROJECT_PATH/excel-mcp.yaml",
        "--profile", "data_workflow",
        "--restart-runtime", "if-stale"
      ],
      "cwd": "YOUR_PROJECT_PATH/"
    }
  }
}

• 开发环境用 --restart-runtime always，生产用 if-stale
• 更多示例见 mcp.example.json 及 examples/ 目录

文档

文档	内容
工具域 Profile 参考手册	Tool / Bundle / Profile 完整对照矩阵与查询索引（V2.5）
Trae AI 使用说明	Trae 推荐 Profile、截断问题与配置示例
v2.4 变更日志	本版新增工具、Bundle 拆分、Profile 重整记录
v2.5 变更日志	新增 Package/Batch/Chart/ConditionalFormat 工具域
OOXML Package 使用指南	直接解析 Excel 文件 ZIP 结构，无需 Excel COM
Batch 批量处理指南	批量提取、变换、比较多个 Excel 文件
Chart 图表指南	图表解析、导出、系列读取