Office MCP

Office MCP

让 AI Agent 在 Windows 上安全地本地操作 Microsoft Excel、Word 和 PowerPoint。

通过 MCP 创建、检查、编辑、分析、制作动画、渲染和验证 Office 文件，同时将访问权限限制在你批准的文件夹内。

这是一个独立的开源项目，与 Microsoft 无关，也未获得其认可。

Office MCP 为负责协调的 AI 提供确定性的 Microsoft Office 操作接口，以及可在交付前验证确切草稿的审阅流程。它可直接处理 .xlsx、.docx 和 .pptx 文件包，也可在 Windows 上调用实际安装的 Excel、Word 和 PowerPoint 应用，实现高保真编辑、计算、图表、数据透视表、PDF 导出、动画和幻灯片渲染。它通过 stdio 在本地运行，无需 API 密钥，并将文件访问范围限制在配置的根目录内。当前支持的发行版本面向 Windows；暂不支持 macOS 和 Linux。

服务器不会决定报告、模型或演示文稿应该写什么。模型负责规划工作，并调用这些工具检查输入、构建文档、渲染结果、进行视觉审阅并迭代修改。

重要

你的文件保留在本地，访问范围也受到限制。 OFFICE_MCP_ROOTS 定义了服务器唯一可读写的目录。请将其指向包含你希望 Agent 使用的文档的最小范围文件夹；根目录之外的路径会被拒绝。

使用 Office MCP 制作

这份 10 页的 Inside an AI Agent 演示文稿使用了原生 Morph 切换效果和定时动画。每张幻灯片都通过 Office MCP 渲染并审阅后，才导出视频。

下载完整 MP4 · 下载可编辑的 PowerPoint

快速开始（Windows PowerShell）

你需要 Node.js 20+ 和一个 MCP 客户端，例如 Codex/ChatGPT 桌面应用或 Claude Code。对于基本的 .xlsx、.docx 和 .pptx 文件创建，桌面版 Microsoft Office 并非必需；但使用动画和 PowerPoint 渲染等 Windows 原生功能时则需要它。

该软件包已发布到 npm，名称为 @parryhotter/office-mcp。

1. 选择 AI 可以访问的文件。此示例允许访问你的 Documents 文件夹；如果你更希望限制范围，请将 $allowed 改为更小的文件夹：

   $allowed = ([Environment]::GetFolderPath('MyDocuments'))
   

2. 连接一个客户端。

   对于 Codex CLI 或 ChatGPT 桌面应用：

   codex mcp add office --env "OFFICE_MCP_ROOTS=$allowed" -- npx -y @parryhotter/office-mcp
   codex mcp list
   

   对于 Claude Code：

   claude mcp add --scope user --env "OFFICE_MCP_ROOTS=$allowed" --transport stdio office -- npx -y @parryhotter/office-mcp
   claude mcp get office
   

3. 重启已打开的桌面客户端，或开始新的聊天。询问：“调用 office_capabilities 并告诉我有哪些 Office 功能可用。”然后尝试：“使用 powerpoint_create_designed_presentation 在我的 Documents 文件夹中创建一份两页的演示文稿，检查它，并报告保存路径。”

客户端会在需要时启动 Office MCP；不要在另一个终端中启动第二个服务器进程。如果你同时使用两个客户端，请在两者中都注册。重新添加之前，请先检查是否已有 office 条目。

可直接复制粘贴的客户端配置

将 C:\\Users\\you\\Documents 替换为 Agent 应可访问的最小范围文件夹。保存配置后，请彻底重启客户端。

{
  "mcpServers": {
    "office": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@parryhotter/office-mcp"],
      "env": {
        "OFFICE_MCP_ROOTS": "C:\\Users\\you\\Documents"
      }
    }
  }
}

{
  "mcpServers": {
    "office": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@parryhotter/office-mcp"],
      "env": {
        "OFFICE_MCP_ROOTS": "C:\\Users\\you\\Documents"
      }
    }
  }
}

{
  "mcpServers": {
    "office": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@parryhotter/office-mcp"],
      "env": {
        "OFFICE_MCP_ROOTS": "C:\\Users\\you\\Documents"
      }
    }
  }
}

{
  "servers": {
    "office": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@parryhotter/office-mcp"],
      "env": {
        "OFFICE_MCP_ROOTS": "C:\\Users\\you\\Documents"
      }
    }
  }
}

{
  "mcpServers": {
    "office": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@parryhotter/office-mcp"],
      "env": {
        "OFFICE_MCP_ROOTS": "C:\\Users\\you\\Documents"
      }
    }
  }
}

配置格式：Claude Desktop · Cursor · VS Code/Copilot。Windsurf 在上方列出的配置路径中使用相同的 mcpServers 结构。

从源代码安装

用于开发、贡献或测试尚未发布的提交：

git clone https://github.com/gauravvvvvvvvvv/office-mcp.git
Set-Location office-mcp
npm ci
npm run build

$entry = (Resolve-Path .\dist\index.js).Path
$allowed = ([Environment]::GetFolderPath('MyDocuments'))

# Pick one client:
codex mcp add office --env "OFFICE_MCP_ROOTS=$allowed" -- node $entry
# claude mcp add --scope user --env "OFFICE_MCP_ROOTS=$allowed" --transport stdio office -- node $entry

为什么选择此服务

• 混合式 Windows 操作：无需启动桌面版 Office 即可直接创建和检查 Office 文件；安装了 Office 时，还可使用原生 Office 自动化。
• 针对提示词的质量标准、文件比较、渲染证据，以及拒绝接受过时或不完整审核结果的最终定稿关卡。
• 默认在后台生成 PowerPoint；不会反复抢占用户的工作焦点。
• 文件系统根目录范围受限、覆盖行为明确，且不提供任意 COM 执行工具。

这些是设计选择，并不能证明此项目比所有替代方案都更强大，或能生成更美观的文档。其 34 个工具的功能范围有意保持有限；最终成果是否达到人工品质，仍取决于编排模型、源材料和视觉审核。

支持的功能

该服务提供 34 个 MCP 工具：

• office_capabilities
• office_inspect_file
• office_search_files
• office_convert_to_pdf
• office_export_pdf
• office_quality_check
• office_compare_files
• office_prepare_review
• office_finalize
• office_get_review_image
• excel_create_workbook
• excel_inspect_workbook
• excel_read_range
• excel_analyze_dataset
• excel_query_dataset
• excel_write_range
• excel_set_formulas
• word_create_document
• word_inspect_document
• word_append_paragraph
• word_replace_text
• powerpoint_create_presentation
• powerpoint_create_designed_presentation
• powerpoint_inspect_presentation
• powerpoint_audit_presentation
• powerpoint_inspect_template
• powerpoint_create_from_template
• powerpoint_replace_text
• office_native_status
• office_list_open_files
• excel_native_batch
• word_native_batch
• powerpoint_native_batch
• powerpoint_render_presentation

要求

• Node.js 20 或更高版本
• 在 Windows 上进行原生自动化、活动文档控制和 PowerPoint 渲染时，需要 Microsoft Office
• 无法使用原生 Office 时，仅使用 LibreOffice 进行便携式 PDF 转换

便携式文件操作无需安装 Microsoft Office。

平台支持

支持的目标平台为 Windows 10/11。直接的软件包操作需要 Node.js，但不需要桌面版 Office。原生自动化、活动文档控制、Excel 重新计算、PowerPoint 动画和 PowerPoint 渲染均需要安装桌面版 Microsoft Office。导出 PDF 可使用桌面版 Office 或 LibreOffice。目前不支持 macOS 和 Linux，也不将其作为受支持的发布目标。

直接的软件包操作会编辑文档文件，不会控制已打开的 Office 窗口。这是一个本地 stdio 服务，而非托管服务：其客户端必须能够启动 Node.js 进程，并访问获准使用的文件。

验证开发检出版本

以下命令供贡献者和维护者使用，安装服务时无需执行：

npm run check
npm run smoke

npm run check 会进行类型检查、运行便携式集成测试，并构建 dist/。npm run smoke 会通过 MCP 客户端启动编译后的服务并创建测试演示文稿。在安装了桌面版 Microsoft Office 的 Windows 上，npm run test:native 还会测试 Excel、Word 和 PowerPoint 的原生行为。请勿在未安装 Office 的计算机上运行该原生测试。

单提示词工作流

对于“分析此文件夹中的财务工作簿并制作一份董事会演示文稿”这类请求，编排器可以：

1. 调用 office_search_files 查找工作簿和模板。
2. 调用 office_inspect_file 或 excel_native_batch 了解数据、公式和工作簿结构。
3. 调用 excel_analyze_dataset 获取确定性的数据质量统计信息，并调用 excel_query_dataset 执行针对性筛选、分组汇总和排序；然后针对业务问题进行推理并规划演示内容。
4. 调用 powerpoint_create_designed_presentation 制作新的叙事型演示文稿，调用 powerpoint_create_presentation 使用自定义版式，或先调用 powerpoint_inspect_template，再调用 powerpoint_create_from_template，以保留公司演示文稿的版式。
5. 如果请求包含动态效果，调用 powerpoint_native_batch 添加对象动画和幻灯片切换效果，然后保存并重新打开文件以检查时间轴。
6. 根据实际提示词定义质量契约，包括必需文本、结构、数值断言，以及编辑时可选的基线源文件。调用 office_quality_check；修复阻断问题。
7. 调用 office_prepare_review 渲染每张幻灯片，或导出 Word/Excel PDF，并检查结果。对于较长的演示文稿，可通过 office_get_review_image 请求内联预览以外的幻灯片。
8. 目视检查对齐、溢出、层级和图表可读性；进行修正后，重新运行检查和渲染。PNG 渲染无法展示动态效果。
9. 调用 office_finalize，为每张幻灯片、每个工作表或每份文档，以及每项提示词标准如实填写通过/未通过说明。它会再次验证草稿、契约、基线、渲染证据和审查覆盖范围，然后复制到单独的最终文件，而不会覆盖原文件。

这就是预期的分工：AI 提供判断；Office MCP 提供可靠的操作接口。

质量关卡与诚实说明限制

office_quality_check 会验证 ZIP 包关系、检查明确的提示词断言，并返回草稿的 SHA-256 哈希值和审查单元。它可以检查 Excel 工作表、表头、精确单元格和公式错误；Word 标题、表格和图像描述；以及 PowerPoint 幻灯片数量、最小字号、演讲者备注和结构审计标记。baseline.path 会将编辑后的文件与源文件进行比较，默认会阻止删除工作表、幻灯片或 Word 段落。契约阈值可以明确允许有意删除，或限制更改的 Excel 单元格范围。office_compare_files 会独立于最终化流程返回详细的语义差异。

office_prepare_review 会创建幻灯片 PNG 或 PDF，并生成与确切草稿、契约和基线关联的清单。若机器检查失败、渲染已过期或不完整、草稿已更改、存在未经审查的单元、标准未通过，或警告未获接受，office_finalize 将拒绝完成。服务无法判断某项说法是否属实、图表是否准确表达了核心内容、设计是否美观，或审阅者是否真正检查过输出。编排器必须如实使用视觉证据和源数据；未经检查的标准不得标记为通过。原生渲染和 PDF 导出需要安装 Office 或 LibreOffice；PowerPoint 幻灯片 PNG 审查则必须使用 Windows 上的桌面版 PowerPoint。

静默后台生成

便携式 PPTX 创建会直接编辑文件，不会打开 PowerPoint。基于本机文件的 PowerPoint 操作现在默认以隐藏窗口的方式创建或打开演示文稿，包括渲染、动画编辑和 PDF 导出。它们不会反复将演示文稿切换到前台。

PowerPoint 自动化在 Windows 上使用共享的应用程序实例。为避免修改或关闭用户正在操作的演示文稿，如果 PowerPoint 已在运行，服务会拒绝基于文件的本机操作。Agent 应继续使用便携式创建，并将本机渲染或动画工作推迟到 PowerPoint 关闭后。target.active: true 会明确选择加入正在运行的会话，而 target.visible: true 会请求显示窗口；未经用户同意，不应使用这两项。本机渲染不提供覆盖活动会话的选项。

提升演示文稿质量

powerpoint_create_designed_presentation 提供五种宽屏构图（cover、imageText、statement、comparison、panorama）和两种视觉风格（editorial、cinematic）。panorama 将宽幅场景与可编辑标题及辅助文案搭配；comparison 可接受可选的 takeaway 来陈述结论。它采用易读的字体，并将提供的图像裁剪至对应画框。故事需要时，请提供相关且各不相同的图像素材；该工具不会生成图像或编造内容。较低级别的 PowerPoint 工具仍可用于图表、表格和精确定位。其图像元素支持 fit: "cover"、"contain" 或 "stretch"。

可选的配套 Codex 技能位于 skills/ 下。安装 office-presentation-quality，用于通用规划、渲染审查和修订。安装 office-morph-storytelling，用于电影化 Morph 序列、持久对象编排、类似摄像机的平移和缩放、定时播放及视频验证。这些技能有助于改进工作流，但无法保证视觉品味，也不能取代优质的参考演示文稿。若要在现有 Codex 会话中使用更新后的服务和技能，请在重新构建 dist/ 后重启该会话。

powerpoint_audit_presentation 可直接检查任何 PPTX，无需打开 Office。它会报告超出幻灯片范围的对象、尺寸明确但字号较小的文本、内容异常密集的幻灯片、缺少有效替代文本的图片、两种颜色均为明确纯色时的低对比度、相互重叠的文本框、空白幻灯片，以及无法可靠测量的组合对象。这些只是审查提示，并不能证明设计欠佳。创建工具接受图像替代文本（自定义图像使用 altText，设计布局使用 imageAltText）；若未提供，则会使用便于审查的占位文本，而不会将本地图像路径泄露到演示文稿中。

复用 PowerPoint 模板

powerpoint_inspect_template 会通过桌面版 PowerPoint 隐藏打开现有的 .pptx，并报告其设计、自定义布局、占位符索引和幻灯片形状名称。随后，powerpoint_create_from_template 可使用这些布局添加幻灯片或复制现有幻灯片、填充占位符或命名文本形状、添加文本框，并另存为单独的 .pptx。它会保留源演示文稿不变，并在输出中移除其原有幻灯片，除非 keepTemplateSlides 为 true。新建本机文本框的坐标单位为点。此功能需要 Windows 桌面版 PowerPoint，并受上述静默后台规则约束；它尚不支持导入 .potx 文件或任意编辑母版。

Word 结构与 Excel 分析

word_create_document 接受原有的 blocks 数组，也接受 sections 数组，其中可分别设置页面大小和方向、页边距、页眉、页脚及页码。区块可包含可更新的 toc、引用用户提供的 sources 的 cited_paragraph、bibliography、带必需替代文本或显式装饰标记的图片、超链接、分页符和脚注。Word 会在更新字段时填充目录条目。引文是经过格式化的文档文本，并非 Word 内置引文管理器中的条目。

原生 Word 批处理支持插入、删除和格式设置的精确字符范围；样式和分节；书签、超链接、字段、脚注、尾注和内容控件；页面设置和分节页眉／页脚；修订列表或全部接受／拒绝；保护；表格、批注、目录和 PDF 导出。范围偏移使用 Word 从零开始的字符位置。指定范围前，请先检查或读取文档；保存后请重新打开文档，以验证字段和版式是否保留。

excel_analyze_dataset 会分析工作表或所选范围，检查缺失行和重复行、列类型、描述性数值统计、IQR 离群值、文本值排名、日期、公式／错误计数，以及最强的 Pearson 相关性。每次调用最多分析 50,000 行和 100 列。它不会清理数据、推断因果关系、运行统计检验，也不会计算未缓存的公式；如果公式结果很重要，请先使用原生 Excel 重新计算。

excel_query_dataset 可读取最多 50,000 行和 100 列，应用类型化筛选条件，可选地进行分组和聚合（count、countDistinct、sum、average、min、max），排序后最多返回 1,000 行。它绝不会写回数据。原生 Excel 批处理还支持结构性行／列编辑、合并、调整大小和隐藏、冻结窗格、复制和设置工作表可见性、表格及调整表格大小、名称、超链接、批注、数据验证、条件格式、图表、数据透视表、删除重复项、单变量求解、排序／筛选、刷新、保护、打印设置、重新计算和 PDF 导出。

动画与切换效果

在安装了桌面 PowerPoint 的 Windows 上，powerpoint_native_batch 可创建和修订幻灯片、文本、形状、线条、图片、媒体和表格；对齐或分布对象；控制叠放顺序和分组；裁剪和校正图片；设置整个文本框或选定字符范围的格式；添加超链接；以及隐藏幻灯片。指定形状前，请调用 list_shapes 获取其稳定名称或当前的从 1 开始的索引。

动画层提供命名的进入效果（appear、fade、fly、wipe、zoom）、强调效果（spin、growShrink）和退出效果，并提供高级 effectId 入口，可使用文档中列出的 MsoAnimEffect 值。它支持触发方式、持续时间、延迟、重复、反向、加速／减速、文本／图表动画级别、序列顺序，以及复合旋转、缩放或运动行为。set_transition 支持 none、cut、fade、向左／向右推入和擦除、放大，以及真正的 PowerPoint Morph（按对象、单词或字符）。要确定性地匹配 Morph，请为成对的形状指定相同且以 !! 开头的名称，复制幻灯片，然后在副本中移动或调整这些形状的大小。export_video 会创建 MP4 或 WMV，并等待 PowerPoint 完成编码。请包含 save 操作，并重新打开结果以验证是否保留。

这是一组持续扩展且经过验证的 Office 功能，并非对所有 Office 命令的封装。我们有意不开放任意 COM 执行。高级 Office 枚举数值是类型化数据，并非可执行代码，且可能取决于已安装的 Office 版本。静态 PNG 渲染器不会捕获动画播放效果。

支持的客户端

快速入门 是 Windows 上最快捷的使用方式。构建好的服务也可与任何能够启动 Node.js 的本地 stdio MCP 客户端配合使用。客户端配置彼此独立：将 Office MCP 添加到 Codex，不会自动将其添加到 Claude Code。

Codex 和 ChatGPT 桌面应用

快速入门中的 codex mcp add 命令会写入 Codex 的用户配置，ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展共用该配置。在 ChatGPT 桌面应用中，添加服务后请重启，然后输入 /mcp 检查服务。你也可以通过 Settings → MCP servers → Add server → STDIO 添加。ChatGPT 网页版不会读取本地 Codex 配置；此仓库不提供托管的 MCP 端点。请参阅 OpenAI 的 MCP 指南。

Claude Code

快速入门使用 Claude Code 的 user 作用域，因此该服务可用于你的所有本地项目。运行 claude mcp list，或在 Claude Code 中使用 /mcp 检查连接状态。请参阅 Claude Code 的 MCP 设置指南。

其他本地 MCP 客户端

将 stdio 服务配置为使用 node 作为命令，将 dist/index.js 的绝对路径作为参数，并将 OFFICE_MCP_ROOTS 设为环境变量。例如，根据客户端的格式调整以下 JSON（所示路径为占位路径）：

{
  "command": "node",
  "args": ["C:\\absolute\\path\\to\\office-mcp\\dist\\index.js"],
  "env": { "OFFICE_MCP_ROOTS": "C:\\allowed\\documents" }
}

安装故障排除

路径安全

默认情况下，服务只能访问其工作目录下的文件。将 OFFICE_MCP_ROOTS 设为一个或多个允许的根目录。

在 Windows 上，多个根目录之间用分号分隔：

C:\Users\your-name\Documents;D:\Company Files

服务会在使用前解析每个输入和输出路径，并拒绝超出这些根目录的路径遍历。

PDF 转换

office_convert_to_pdf 会以无界面模式使用 LibreOffice。服务会检查标准安装位置和系统 PATH。对于自定义安装，请设置：

OFFICE_MCP_SOFFICE=C:\path\to\LibreOffice\program\soffice.exe

调用 office_capabilities 查看是否检测到转换器。

开发

npm run dev

该进程会静默等待标准输入中的 MCP 消息。不要将日志写入标准输出，因为 stdout 承载 MCP 协议。诊断信息应写入 stderr。

手动发布

此仓库没有 GitHub Actions 工作流或 Dependabot 配置。推送或拉取请求不会触发任何自动运行，推送标签也不会创建发布版本或发布到 npm。这是一个本地 stdio 服务，而非托管的 Office 服务。

公开的 npm 包为 @parryhotter/office-mcp。目前，发布版本均由人工完成。发布新版本前，请更新 package.json 和锁文件；运行 npm run check 和 npm run smoke；并在配备桌面版 Office 的 Windows 系统上运行 npm run test:native。在运行 npm publish --access public 前，请验证全新安装的打包版本，并审计捆绑的依赖项。发布公开版本时，请创建对应的 GitHub Release。请参阅 CONTRIBUTING.md 和 SECURITY.md。

重要限制

• 原生的活动文档控制需要 Windows 和已安装的桌面版 Microsoft Office。其他操作系统不在当前版本的支持范围内。
• ExcelJS 不支持所有 Excel 功能。重新保存复杂工作簿时，可能无法保留嵌入式图表或 VBA 项目等不受支持的对象。编辑重要文件时，建议使用单独的 outputPath。
• Word 和 PowerPoint 的替换操作可以匹配拆分在多个格式运行中的文本。如果替换内容跨越多个运行，替换文本会合并到第一个运行中，因此该短语内部的混合字符格式不会保留。
• PowerPoint 创建采用声明式方式。位置和尺寸以英寸为单位，与 PptxGenJS 的约定一致。
• 设计布局仅供起步使用。可通过原生 PowerPoint 重用模板，但不会导入 .potx、任意编辑母版或自动评估美观性。交付前请检查渲染结果。
• PPTX 审计无法判断文本是否实际适配、从主题或图像背景继承的对比度是否足够，也无法评估内容脉络和美观性。请目视检查渲染后的幻灯片。
• 对象动画和幻灯片切换效果的编辑目前需要在 Windows 上使用桌面版 PowerPoint。静态幻灯片图像只能验证视觉布局，无法展示放映时效果的播放情况。
• 如果 PowerPoint 已在运行，原生 PowerPoint 的后台工作可能会延后执行。隐藏演示文稿可避免弹出窗口，但这并非完全隔离的无头 PowerPoint 服务。
• 公式值会写入，但不会由 Node.js 计算。工作簿会被标记为在 Excel 中打开时重新计算。
• 此服务不提供 Microsoft Office 的所有命令，也不会充当自主设计模型。质量仍取决于编排模型、源素材、模板和渲染结果审查。

技术

• MCP TypeScript SDK
• 用于 .xlsx 的 ExcelJS
• 用于创建文档的 docx
• 用于创建演示文稿的 PptxGenJS
• 用于保留结构的 OOXML 检查和定向编辑的 JSZip

许可证

MIT