groupdocs-editor-mcp

GroupDocs.Editor MCP 服务

让 Claude、Cursor、GitHub Copilot 和任何其他 MCP Agent 编辑 Word、Excel、PowerPoint、PDF 和文本文档，同时不破坏其格式——就地替换文本，将文档（或单个工作表、幻灯片或 PDF 页面范围）转换为可编辑 HTML 并往返处理，以及填写 Word 表单字段。 本地运行：文件绝不会离开你的设备。

60 秒内完成安装

一键安装会预填所有受支持的设置：安装后请修改占位文档文件夹（输出默认保存到同一文件夹）；如果 GROUPDOCS_LICENSE_PATH 为空，则以评估模式运行——将其指向你的许可证即可解除限制。

更多客户端——Claude Code、Codex CLI、Visual Studio 2022、Cursor、Windsurf、Cline 和 JetBrains Rider 的现成配置位于 install/generated/。

原生运行需要 .NET 10 SDK，也可以直接使用 Docker。

使用 dnx 直接运行（推荐——无需安装）：

dnx GroupDocs.Editor.Mcp --yes

每次运行都会拉取最新的稳定版本。若要固定版本（共享配置和 CI 推荐采用此方式），请追加 @<version>：

dnx [email protected] --yes

服务会在 GROUPDOCS_MCP_STORAGE_PATH 中读取和写入文档（默认值：当前目录）。编辑后的副本会保存在原文件旁，且绝不会覆盖已有文件。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "groupdocs-editor": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Editor.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
      }
    }
  }
}

如需使用许可证，请将 "GROUPDOCS_LICENSE_PATH": "/path/to/GroupDocs.Editor.lic" 添加到 env — 如要在评估模式下运行，则省略此项。

Claude Code

claude mcp add groupdocs-editor -- dnx GroupDocs.Editor.Mcp --yes

VS Code / GitHub Copilot

使用上方的 Install in VS Code 按钮，或将 NuGet 包页面上的现成代码片段复制到 .vscode/mcp.json， 或者从此仓库中获取 install/generated/vscode-mcp.json。

Visual Studio 2022 (17.14+)

在解决方案根目录中创建 .mcp.json，内容取自 install/generated/vs2022-mcp.json。

Cursor · Windsurf · Cline · Rider · Codex

• Cursor — 使用上方的 Add to Cursor 按钮，或将 install/generated/claude-desktop.json 粘贴到 ~/.cursor/mcp.json。
• Windsurf — 按照 install/generated/windsurf.md 操作。
• Cline — 将 install/generated/cline.json 粘贴到 Cline 的 MCP 设置中。
• JetBrains Rider — 按照 install/generated/rider.md 操作。
• Codex CLI — codex mcp add groupdocs-editor -- dnx GroupDocs.Editor.Mcp --yes，详情见 install/generated/codex.md。

Docker

docker run --rm -i \
  -v "$(pwd)/documents:/data" \
  ghcr.io/groupdocs-editor/editor-net-mcp:latest

镜像发布于 GHCR（ghcr.io/groupdocs-editor/editor-net-mcp）和 Docker Hub （groupdocs/editor-net-mcp），支持 linux/amd64 和 linux/arm64，标记为 latest，并带有与每个 NuGet 版本对应的不可变版本标签（例如 :26.10.0）。该镜像无需原生环境配置。

Linux 上的 Docker：以当前用户身份运行容器

镜像以非 root 用户（uid 1654）运行，绑定挂载会保留宿主机上的所有者身份 — 因此在 Linux 主机上，如果容器不以当前用户身份运行，服务写入 /data 的所有已编辑文件都会报错：Permission denied：

docker run --rm -i --user "$(id -u):$(id -g)" \
  -v "$(pwd)/documents:/data" \
  ghcr.io/groupdocs-editor/editor-net-mcp:latest

JSON 客户端配置不会运行 shell，因此请直接填写数字："args": ["run", "--rm", "-i", "--user", "1000:1000", …]。Docker Desktop 在 Windows 和 macOS 上无需此设置。

全局 dotnet 工具

dotnet tool install -g GroupDocs.Editor.Mcp
groupdocs-editor-mcp

可用的 MCP 工具

工具	功能
get_document_info	文件格式系列、格式、页数 / 工作表数 / 幻灯片数、大小、加密状态，以及可另存为的格式（JSON）
extract_html	将文档 — 或单个工作表、单张幻灯片或一段 PDF 页面 — 转换为可编辑的 HTML 并保存到存储中，同时提供纯文本预览。默认独立完整；embedResources=false 会写入一个 <name>_resources 文件夹
save_from_html	将编辑后的 HTML 另存为 DOCX、DOC、RTF、ODT、XLSX、XLS、ODS、CSV、PPTX、PPT、ODP、PDF、XPS、TXT、Markdown、MHTML、EPUB、MOBI、AZW3、EML 或 MSG。搭配 sourceFile 和 worksheet / slide 使用时，会将一个编辑后的部分合并回原文件，并保留其他所有部分
replace_text	查找并替换，同时保留格式 — 支持字面匹配、忽略大小写、全字匹配或正则表达式；每次处理一个工作表或一张幻灯片；可选输出格式。报告更改的匹配项数；未匹配到内容时不会写入任何内容
get_supported_formats	GroupDocs.Editor 可打开和保存的格式（按系列分类），或单个文件的可保存格式（JSON）
get_form_fields	列出 Word 文档中的表单字段 — 文本框、复选框、下拉框、数字字段和日期字段 — 并显示类型和值（JSON）
fill_form_fields	填充 Word 表单字段并保存已填充的副本；报告未知名称和不合适的值，绝不会忽略
get_license_status	许可模式、按量计费消耗量和引擎版本（由 GroupDocs.Mcp.Core 提供）

工作表、幻灯片和页面编号均从 1 开始。每次失败都会设置 isError，并以工具前缀开头，例如 HTML extraction failed for 'report.docx': …，因此客户端只需进行一次检查。

面向 AI Agent 的提示词示例

Replace "ACME Corp" with "Globex" in contract.docx and keep the formatting.
Give me the second worksheet of budget.xlsx as HTML so I can edit it.
Save edited.html back as a Word document, and also as a PDF.
Fill the form fields in application.docx: name = Jane Doe, agree = yes.
Which formats can GroupDocs.Editor open and save?

评估模式

MCP 服务本身采用 MIT 许可证；GroupDocs.Editor 引擎在生产环境中使用时需要许可证。 没有许可证时，所有工具仍可运行，但有以下限制（基于 GroupDocs.Editor 26.6.1 测得）：

• 编辑后的输出会以评估横幅开头（“Created with evaluation version of GroupDocs.Editor …”）。
• 保存的工作簿会多出一个工作表。
• 只能编辑 PDF 的前 2 页、工作簿中前 2 个（可见）工作表，以及演示文稿的前 2 张幻灯片。对于更大的序号，引擎会静默返回第 2 部分；服务则会拒绝请求并说明原因。将编辑后的部分保存回第 3 个及之后的工作表或幻灯片不受限制。

此时，编辑工具的响应会以一行 Evaluation mode: 开头。调用 get_license_status 可查看当前启用的模式。

许可

服务有两种许可方式。

许可证文件 — 将 GROUPDOCS_LICENSE_PATH 指向你的 GroupDocs.Editor（或 GroupDocs.Total）许可证文件。可离线使用。

计量付费（按使用量付费） — 设置 GROUPDOCS_METERED_PUBLIC_KEY 和 GROUPDOCS_METERED_PRIVATE_KEY。按处理量付费，适合 Agent 工作负载。如果同时配置了计量密钥对和许可证文件，计量付费优先，许可证文件将被忽略。

计量模式需要出站网络连接。 使用情况会报告给 GroupDocs 服务器，因此，气隙隔离或有防火墙的部署必须允许此类出站连接，或改用许可证文件。

避免在配置中暴露私钥

计量私钥属于机密信息。MCP 客户端配置是纯文本文件，而且项目范围的 .mcp.json 通常会提交到版本库，因此建议按以下优先顺序处理：

1. 在操作系统环境中设置变量，完全不将它们写入配置——stdio MCP 服务会继承其客户端的环境变量。在 macOS 上，从 Finder 启动的应用不会继承 shell 导出的变量；请使用 launchctl setenv，或从终端启动客户端。
2. 如果客户端支持，间接引用变量（Claude Code 会展开 ${VAR}；VS Code 使用 ${env:VAR} 和 ${input:...}）。
3. 对于单个开发者，在用户范围的配置中填写字面值（例如 ~/.claude.json）是可以接受的。
4. 切勿将包含字面密钥的项目范围 .mcp.json 提交到版本库。

对于 Docker，请转发这些值，不要将它们写入任何文件：

docker run --rm -i \
  -e GROUPDOCS_METERED_PUBLIC_KEY -e GROUPDOCS_METERED_PRIVATE_KEY \
  -v /path/to/documents:/data \
  ghcr.io/groupdocs-editor/editor-net-mcp:latest

• 获取免费的 30 天临时许可证
• 购买许可证 · 产品页面

配置

变量	描述	默认值
GROUPDOCS_MCP_STORAGE_PATH	输入和输出文件的基础文件夹	当前目录
GROUPDOCS_MCP_OUTPUT_PATH	*（可选）*用于输出文件的独立文件夹	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_LICENSE_PATH	GroupDocs 许可证文件的路径	（评估模式）
GROUPDOCS_METERED_PUBLIC_KEY	计量公钥。也需要私钥；优先于许可证文件	（未设置）
GROUPDOCS_METERED_PRIVATE_KEY	计量私钥。机密——参见许可	（未设置）

原生依赖项

GroupDocs.Editor 通过 Aspose.Drawing（托管）和 SkiaSharp 绘制内容；它们的原生库随软件包一起提供——所有平台上均不需要 libgdiplus。将编辑后的内容保存为 PDF 或 XPS 时需要进行文本排版，因此 Linux 需要安装真实字体：

平台	设置
Windows	无需设置。
Linux	sudo apt-get install -y libfontconfig1 ttf-mscorefonts-installer（仅用于 PDF/XPS 输出）
macOS	无需设置。
Docker	无需设置——映像中已包含字体。

限制

• replace_text 只能匹配同一格式文本段中的内容。 如果短语被拆分为格式不同的文本（部分加粗，部分未加粗），则无法匹配；此类编辑请使用 extract_html 和 save_from_html。
• 编辑 PDF 需要进行转换。 PDF 会先转换为流式 HTML，再转回 PDF，因此复杂布局无法完美还原。如果对保真度有要求，请将编辑结果保存为 DOCX。
• 输出 PPTX 和邮件需要原始文件。 save_from_html 仅凭 HTML 即可创建 DOCX、XLSX、PDF、TXT、Markdown 和 EPUB；要创建 PPTX 和 EML/MSG，请将原始文件作为 sourceFile 传入。
• 远程资源。 引用了远程图片或样式表的 HTML 或 Office 输入文件，可能会导致引擎在加载时获取这些资源。如果输入内容不可信，请在禁止网络出站访问的环境中运行服务。
• macOS CI。 集成测试在 Linux 和 Windows 上运行；macOS 全系列运行器挂起的问题正在单独跟踪。

使用 Docker Compose

cd docker
docker compose up

编辑 docker/docker-compose.yml，将卷路径指向你的文档文件夹。

文档与指南

分步部署指南和已发布软件包集成测试套件位于配套仓库 GroupDocs.Editor.Mcp.Tests：

• 从 NuGet 安装 — dnx、全局工具、固定版本与始终使用最新版本
• 通过 Docker 运行
• 在 MCP 注册表中验证
• 与 Claude Desktop 搭配使用
• 与 VS Code / GitHub Copilot 搭配使用
• 运行集成测试
• 与 Cursor 搭配使用

该仓库会使用已发布的软件包（通过 Linux、Windows 和 macOS 上的 dnx）及 Docker 镜像，测试所有宣传的工具，并通过服务读取每项编辑结果。

许可证

MIT — 参见 LICENSE