groupdocs-markdown-mcp

GroupDocs.Markdown MCP 服务

MCP 服务将 GroupDocs.Markdown 提供为可由 AI 调用的工具，供 Claude、Cursor、GitHub Copilot 和其他 MCP Agent 使用——将文档转换为整洁、结构化的 Markdown。

安装

一键安装会预先填入所有受支持的设置：安装后请编辑占位文档文件夹（输出默认使用同一文件夹）；GROUPDOCS_LICENSE_PATH 为空时将以评估模式运行——指定许可证路径即可解除限制。

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

需要 .NET 10 SDK。

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

dnx GroupDocs.Markdown.Mcp --yes

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

dnx [email protected] --yes

或安装为全局 dotnet 工具：

dotnet tool install -g GroupDocs.Markdown.Mcp
groupdocs-markdown-mcp

或通过 Docker 运行：

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

任何平台均无需本机前置依赖——底层的 GroupDocs.Markdown 引擎通过自包含的 SkiaSharp 本机资产来渲染包含图像的文档，因此 dnx、全局工具和 Docker 镜像均无需额外配置 apt/brew 即可运行。

可用的 MCP 工具

工具	描述
ConvertToMarkdown	将文档（PDF、DOCX、XLSX、EPUB、MOBI 等）转换为整洁、结构化的 Markdown，并将 .md 文件保存到存储中。默认将图像嵌入为 base64。
GetDocumentInfo	以 JSON 格式返回文件格式、页数、标题、作者和加密标记，不进行转换。

底层 GroupDocs.Markdown 26.3.0 引擎尚未实现反向 Markdown → 文档的生成功能（MarkdownConverter.FromMarkdownString 会抛出 NotImplementedException），因此此服务不会提供 ComposeFromMarkdown 工具。如需现在将 Markdown 转换为 DOCX / PDF / HTML，请使用 GroupDocs.Conversion MCP，并提供 .md 源文件。

面向 AI Agent 的提示词示例

• “将 report.pdf 转换为 Markdown”
• “将 business-plan.docx 导出为 Markdown，并将图像嵌入为 base64”
• “将 contract.pdf 的第 1-3 页转换为 Markdown，仅提取文本，跳过图像”
• “business-plan.pdf 有多少页？”
• “cost-analysis.xlsx 的格式和作者是什么？”

许可

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

• 输出可能受限，并带有评估提示。
• 单个服务进程最多可打开 15 份文档；超出后，后续调用会失败并提示超出评估上限，直到服务重启。

服务有两种许可方式。

许可证文件 — 将 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-markdown/markdown-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	计量私钥。机密 — 请参阅许可	（未设置）

在评估模式下（没有许可证），转换后的 Markdown 可能会受到限制，并可能包含评估说明。提供 GROUPDOCS_LICENSE_PATH 即可获得不受限制的输出。

在 Claude Desktop 中使用

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

若要固定到特定版本，请在 args 中将 "GroupDocs.Markdown.Mcp" 替换为 "[email protected]"。建议在共享或提交的配置中固定版本，以避免意外升级。

在 VS Code / GitHub Copilot 中使用

NuGet.org 会在程序包页面生成可直接使用的 mcp.json 片段。 将其直接复制到 .vscode/mcp.json 中。

也可以手动添加到 .vscode/mcp.json：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-markdown": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Markdown.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "${input:storage_path}"
      }
    }
  }
}

固定版本的规则与上面相同 — 将 "GroupDocs.Markdown.Mcp" 替换为 "[email protected]"，即可锁定到特定版本。

使用 Docker Compose

cd docker
docker compose up

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

文档和指南

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

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

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

许可证

MIT — 请参阅 LICENSE