excel-mcp

Excel MCP 服务技能

通过 Model Context Protocol 提供 326 项 Excel 操作。MCP 服务在进程内托管 ExcelMCP Service，并直接调用它，实现低延迟的 Excel 自动化。工具会自动发现——本文档介绍其中的特殊情况、工作流和注意事项。

工作流检查清单

步骤	工具	操作	适用时机
1. 打开文件	file	open 或 create	始终首先执行
2. 创建工作表	worksheet	create、rename	如有需要
3. 写入数据	range	set-values	始终执行（二维数组）
4. 设置格式	range	set-number-format	写入数据后
5. 设置结构	table	create	将数据转换为表格
6. 保存并关闭	file	使用 save: true 执行 close	始终最后执行

前置条件

• 安装了 Microsoft Excel（2016+）的 Windows 主机
• 使用完整的 Windows 路径：C:\Users\Name\Documents\Report.xlsx
• Excel 文件不得在另一个 Excel 实例中打开

计算模式工作流（批量性能）

使用 calculation_mode 优化批量写入性能。写入大量值或公式时，请关闭自动重新计算，避免每次修改单元格后都重新计算：

1. calculation_mode(action: 'set-mode', mode: 'manual')  → Disable auto-recalc
2. Perform all writes (range set-values, set-formulas)
3. calculation_mode(action: 'calculate', scope: 'workbook')  → Recalculate once
4. calculation_mode(action: 'set-mode', mode: 'automatic')  → Restore default

**注意：**读取公式时不需要手动模式——无论计算模式如何，range get-formulas 都会返回公式文本。

关键：执行规则（必须遵守）

规则 1：绝不提问澄清问题

**停下。**如果你正准备询问“要用哪个文件？”“要用哪个表格？”“应该放在哪里？”——不要问。

不好的做法（提问）	好的做法（自行查找）
“应该使用哪个 Excel 文件？”	file(list) → 使用已打开的会话
“表格叫什么名字？”	table(list) → 查找表格
“哪个工作表包含数据？”	worksheet(list) → 检查所有工作表
“要创建数据透视表吗？”	是——在新工作表中创建

你有工具可以自行解答这些问题。使用它们。

规则 2：始终以文本摘要结束

**绝不要只以工具调用结束你的回复。**完成所有操作后，始终提供一条简短的文本消息，确认已完成的事项。只调用工具而不回复文本是不完整的。

规则 3：以专业方式设置数据格式

设置值后，始终应用数字格式：

数据类型	格式代码	结果
USD	$#,##0.00	$1,234.56
EUR	€#,##0.00	€1,234.56
百分比	0.00%	15.00%
日期（ISO）	yyyy-mm-dd	2025-01-22

无论机器的区域设置如何，格式代码都使用美国格式（, 分组，. 小数）——Excel 会进行转换。显示的分隔符遵循用户的 Windows 区域设置，因此在德国系统上，$#,##0.00 会显示为 $1.234,56。不要通过调换格式代码中的分隔符来“修复”这一点，否则会导致其他所有区域设置出错。

工作流：

1. range set-values (data is now in cells)
2. range set-number-format (apply format)
3. range_format auto-fit-columns (formatted values are wider than raw ones)

步骤 3 不可省略。适合显示 45678 的列宽，在该值显示为 2025-01-22 或 $1,234.56 后就会过窄，Excel 会显示 #####，而不是数字。

规则 4：使用 Excel 表格（而非普通区域）

始终将表格数据转换为 Excel 表格：

1. range set-values (write data including headers)
2. table(action: 'create', table_name: 'SalesData', range_address: 'A1:D100')

**原因：**结构化引用、自动扩展，以及数据模型/DAX 的必要条件。

规则 5：会话生命周期

1. file(action: 'open', path: '...')  → capture response.session_id as sessionId
2. workbook(action: 'get-info', session_id: sessionId)
3. file(action: 'close', session_id: sessionId, save: true)  → saves and closes

在每次基于会话的后续调用中，将同一个值作为 session_id 传入。 上面的 sessionId 是一个局部变量，不是 MCP 参数名称。从 file(list) 复用 会话时，请将匹配条目的 sessionId 值复制到 session_id 中。绝不要猜测或替换会话。

未关闭的会话会导致 Excel 进程持续运行并锁定文件。

规则 6：数据模型前置条件

DAX 操作要求数据模型中包含表格：

Step 1: Create table → Table exists
Step 2: table(action: 'add-to-data-model') → Table in Data Model
Step 3: datamodel(action: 'create-measure') → NOW this works

规则 7：Power Query 开发生命周期

最佳实践：测试优先工作流

1. powerquery(action: 'evaluate', m_code: '...') → Test WITHOUT persisting
2. powerquery(action: 'create', ...) → Store validated query
3. powerquery(action: 'refresh', ...) → Load data

为什么要先评估：

• 在创建永久查询之前捕获语法错误和缺失的数据源
• 错误信息比创建或更新时的 COM 异常更清晰
• 查看实际数据预览（列和示例行）
• 无需清理——就像 M 代码的 REPL
• 只有简单的字面值表格可以跳过

常见错误： 未评估就创建或更新 → 工作簿中会留下损坏的查询

规则 8：优先进行定向更新，而不是删除后重建

• 优先选择：对特定区域使用 set-values（例如，对第 5 行使用 A5:C5）
• 避免：删除并重新创建整个结构

原因： 保留格式、公式和引用。

规则 9：遵循 suggestedNextActions

错误响应中包含可执行的提示：

{
  "success": false,
  "errorMessage": "Table 'Sales' not found in Data Model",
  "suggestedNextActions": ["table(action: 'add-to-data-model', table_name: 'Sales')"]
}

工具选择快速参考

任务	工具	关键操作
创建/打开/保存工作簿	file	open、create、close
写入/读取单元格数据	range	set-values、get-values
设置单元格格式	range	set-number-format
根据数据创建表格	table	create
将表格添加到 Power Pivot	table	add-to-data-model
创建 DAX 公式	datamodel	create-measure
创建数据透视表	pivottable	create、create-from-datamodel
使用切片器筛选	slicer	set-slicer-selection
创建图表	chart	create-from-range
运行假设分析	analysis	goal-seek、create-scenario、create-data-table
控制计算模式	calculation_mode	get-mode、set-mode、calculate
视觉验证	screenshot	capture、capture-sheet

参考文档

详细指南请参阅 references/：

• 假设分析和 Solver 限制
• 核心执行规则和 LLM 指南
• 应避免的常见错误
• 批量写入性能优化
• 数据模型约束和模式
• 图表和格式设置
• 条件格式操作
• 仪表板和报告最佳实践
• 数据模型/DAX 详细说明
• 用于数据模型分析的 DMV 查询参考
• Excel Agent 模式和高级自动化
• 注意事项和已知限制
• Power Query M 代码语法参考
• 数据透视表操作
• Power Query 详细说明
• 区域操作和数字格式
• 截图和视觉验证
• 切片器操作
• 表格操作
• 窗口和可见性操作
• 工作表操作