groupdocs-conversion-mcp

GroupDocs.Conversion MCP 服务

通过 Claude、Cursor、GitHub Copilot 和任何其他 MCP Agent 转换 PDF、Word、Excel、PowerPoint、HTML、图像及 70 多种文档格式 — 在本地运行，文件绝不会离开你的设备。

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.Conversion.Mcp --yes

每次运行都会拉取最新的稳定版本。若要固定到特定 版本（建议用于共享配置和 CI），请追加 @<version>：

dnx [email protected] --yes

Claude Desktop

添加到 claude_desktop_config.json：

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

若要使用许可证，请在 env 中添加 "GROUPDOCS_LICENSE_PATH": "/path/to/GroupDocs.Total.lic" — 不添加则以评估模式运行。

Claude Code

claude mcp add groupdocs-conversion -- dnx GroupDocs.Conversion.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 的内容——其格式与 VS Code 的相同。 这是已在 Visual Studio 中工作的 .NET 团队的原生接入方式。

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-conversion -- dnx GroupDocs.Conversion.Mcp --yes，详情请参阅 install/generated/codex.md。

Docker

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

镜像同时发布到 GHCR（ghcr.io/groupdocs-conversion/conversion-net-mcp）和 Docker Hub（groupdocs/conversion-net-mcp），支持 linux/amd64 和 linux/arm64，标签包括 latest 以及与每个 NuGet 版本对应的不可变版本标签（例如 :26.9.0）。

全局 dotnet 工具

dotnet tool install -g GroupDocs.Conversion.Mcp
groupdocs-conversion-mcp

**固定版本：**在上述任何代码片段中，将 "GroupDocs.Conversion.Mcp" 替换为 "[email protected]"，即可锁定到特定版本。建议在共享或提交到版本控制的配置中固定版本，以避免意外升级。

可用的 MCP 工具

工具	描述
Convert	将文档转换为其他格式（PDF、DOCX、XLSX、PPTX、HTML、PNG、JPG 等 70 多种格式），并将结果保存到存储中
GetSupportedFormats	列出源文档可转换到的所有目标格式，并标明主要格式和次要格式
GetDocumentInfo	返回源文档的文件类型、页数和基本属性（作者、标题、日期、是否受密码保护）

许可

MCP 服务本身采用 MIT 许可；底层的 GroupDocs.Conversion 引擎在生产环境中使用时需要许可证。未提供许可证时，服务将在评估模式下运行：

• 转换后的输出会带有评估水印，工具响应中也会包含评估模式提示。
• 单个服务进程最多只能打开 15 个文档；超出后，后续调用会失败，并提示 "Could not open more than 15 document files in evaluation mode"，直到服务重启。

有两种方式为服务授权。

许可证文件 — 将 GROUPDOCS_LICENSE_PATH 指向 GroupDocs.Total.lic。可离线使用。

按量计费 — 同时设置 GROUPDOCS_METERED_PUBLIC_KEY 和 GROUPDOCS_METERED_PRIVATE_KEY。您只需为实际处理的内容付费，非常适合 AI Agent，因为其用量往往呈突发式，且难以提前预测。如果同时配置了按量计费密钥对和许可证文件，将优先使用按量计费，许可证文件会被忽略。

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

随时调用 get_license_status 工具，即可查看当前激活的模式，以及在按量计费模式下已消耗的用量和剩余额度。

避免配置文件中包含私钥

计量私钥属于机密信息。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-conversion/conversion-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 引擎在部分操作中会使用 System.Drawing（GDI+）。在 Linux 或 macOS 上原生运行服务（通过 dnx 或全局 dotnet 工具）时，请先安装原生 libgdiplus 库：

平台	设置
Windows	无需操作——GDI+ 已内置于操作系统中。
Linux	sudo apt-get install -y libgdiplus libfontconfig1 ttf-mscorefonts-installer
macOS	brew install mono-libgdiplus
Docker	无需操作——镜像已包含 libgdiplus。

在 Linux/macOS 上跳过此步骤会导致工具响应中出现 DllNotFoundException: libgdiplus。在 Linux/macOS 上最简单、无需任何设置的选项是使用Docker 镜像。

使用 Docker Compose

cd docker
docker compose up

编辑 docker/docker-compose.yml，将卷指向本地文档文件夹。

文档与指南

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

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

该仓库还会在 CI 中针对 Linux、macOS 和 Windows，使用已发布的 NuGet 包测试所有宣传的工具——因此，上述代码片段会在每次发布时经过端到端验证。

许可证

MIT — 详见 LICENSE