groupdocs-parser-mcp

GroupDocs.Parser MCP 服务

将 GroupDocs.Parser 封装为可供 Claude、Cursor、GitHub Copilot 和其他 MCP Agent 调用的工具的 MCP 服务。

安装

一键安装会预先填入所有受支持的设置：安装后，请编辑卷挂载中的占位主机路径；GROUPDOCS_LICENSE_PATH 为空时将以评估模式运行。

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

本产品仅通过 Docker（GHCR）分发。 GroupDocs.Parser 的托管 DLL 内嵌了约 234 MB 的 ONNX 模型，因此打包后的工具超过 NuGet.org 的 250 MB 限制，无法使用 dnx 和 dotnet tool install。上游发布能够在限制内打包的精简引擎后，标准 NuGet 安装流程将恢复 （请参阅 .github/workflows/publish_prod.yml 中的回退说明）。

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

镜像支持多架构（linux/amd64 + linux/arm64），每个版本均带有 latest 标签和不可变的版本标签（例如 :26.10.2）。如需固定版本，请将 :latest 替换为版本标签；建议在共享配置和 CI 中这样做。

Linux：以你的用户身份运行容器

该映像以非 root 用户（uid 1654）运行。在 Linux 上，挂载的文件夹会保留其主机所有者，因此你拥有的文件夹在容器内是只读的，extract_images 无法保存文件——错误信息以 "Fix: the server cannot write to the output folder" 结尾。添加 --user，让容器以你的身份写入：

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

MCP 客户端配置（JSON）不会运行 shell，因此请直接填写数字——id -u 和 id -g 会显示这些数字，通常是 1000："args": ["run", "--rm", "-i", "--user", "1000:1000", "-v", …]。 只读工具（extract_text、extract_tables、extract_metadata、extract_barcodes、 get_document_info）无需此设置。Windows 和 macOS 上的 Docker Desktop 不需要此设置。

可用的 MCP 工具

工具	描述
extract_text	从文档中提取纯文本（整个文档或单页）。输出过大时会截断。
extract_images	提取所有嵌入的图像，并将其保存到存储中，文件名为 <basename>_image<N>.<ext>
extract_metadata	提取元数据（作者、标题、日期、自定义属性、EXIF、XMP、IPTC），并以 JSON 格式返回
extract_tables	将文档中的表格提取为 Markdown（默认格式，可在聊天中呈现）或结构化 JSON
extract_barcodes	检测所有条形码 / QR 码，并以 JSON 格式返回其解码值、类型和位置
get_document_info	以 JSON 格式返回文档的文件类型、页数和大小（不修改文档）
get_license_status	报告当前的许可模式（evaluation / licensed / metered）、引擎版本，以及在 metered 模式下已消耗的数量和额度。不处理任何文档。

所有工具均支持 PDF、DOCX、XLSX、PPTX、HTML、EPUB、MSG、EML、JPG、PNG、TIFF 及 50 多种其他文档和图像格式。

面向 AI Agent 的提示词示例

连接服务后，可将以下任意提示词复制到 Claude Desktop、Cursor 或 GitHub Copilot Chat 中。

1. 获取文档结构：“invoice.pdf 有多少页，文件格式是什么？”
2. 提取一段文本：“提取 contract.docx 第 2 页的文本。”
3. 提取元数据：“report.xlsx 的作者和创建日期是什么？”
4. 读取结构化表格：“将 invoice.pdf 中的明细表提取为 Markdown。”
5. 扫描条形码：“shipping-label.png 中有 QR 码吗？如果有，解码结果是什么？”

许可

MCP 服务本身采用 MIT 许可；底层的 GroupDocs.Parser 引擎在生产环境中使用需要许可证。 如果没有许可证，服务将以评估模式运行，且限制会严重影响提取结果——输出看起来有效，但内容会在不提示的情况下被截断：

• 文本提取：每个文件仅提取前 1,600 个字符和 20 行，且仅处理前 5 页、工作表或幻灯片。格式化文本和结构提取还会对电子表格额外施加 20 行上限。
• 元数据提取：每个文件仅提取 5 个属性。
• 每个会话最多处理 100 个文件，且输出会带有评估标记。
• 完整列表：评估限制。

有两种方式可以为服务授权。

许可证文件——将你的 GroupDocs.Parser.lic（或 GroupDocs.Total.lic）挂载到容器中，并将 GROUPDOCS_LICENSE_PATH 指向该文件，如上文的 Claude Desktop 示例所示。可离线使用。

按量计费——设置 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-parser/parser-net-mcp:latest

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

配置

变量	描述	默认值
GROUPDOCS_MCP_STORAGE_PATH	输入和输出文件的基础文件夹	当前目录
GROUPDOCS_MCP_OUTPUT_PATH	(可选) 单独的输出文件文件夹（供 extract_images 使用）	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_LICENSE_PATH	GroupDocs 许可证文件的路径（以容器内可见的路径为准）。设置按量计费密钥后，此变量将被忽略	（评估模式）
GROUPDOCS_METERED_PUBLIC_KEY	按量计费公钥。还需要私钥；优先级高于 GROUPDOCS_LICENSE_PATH	（未设置）
GROUPDOCS_METERED_PRIVATE_KEY	按量计费私钥。机密——请通过环境传入，绝不要写入已提交的配置	（未设置）

在 Claude Desktop 中使用

{
  "mcpServers": {
    "groupdocs-parser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/documents:/data", "ghcr.io/groupdocs-parser/parser-net-mcp:latest"]
    }
  }
}

要使用许可证，请在镜像名称前添加 "-v", "/path/to/license-folder:/license", "-e", "GROUPDOCS_LICENSE_PATH=/license/GroupDocs.Total.lic"。 要固定版本，请将 :latest 替换为发布标签。

在 VS Code / GitHub Copilot 中使用

使用上方的 Install in VS Code 按钮，或添加到 .vscode/mcp.json （也位于 install/generated/vscode-mcp.json）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-parser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "${input:storage_path}:/data", "ghcr.io/groupdocs-parser/parser-net-mcp:latest"]
    }
  }
}

使用 Docker Compose

cd docker
docker compose up

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

文档与指南

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

• 从 NuGet 安装
• 通过 Docker 运行
• 在 MCP 注册表上验证
• 与 Claude Desktop 搭配使用
• 与 VS Code / GitHub Copilot 搭配使用
• 运行集成测试

许可证

MIT — 请参阅 LICENSE