Docling MCP：通过 Model Context Protocol 让 AI Agent 直接调用文档解析能力

2026-09-06 13:53:26作者：龚格成

本文围绕 Docling 官方文档 docs/usage/mcp.md 展开，讲解如何利用 MCP（Model Context Protocol）把 Docling 的文档理解能力暴露给各类 AI Agent 客户端（Claude Desktop、LM Studio 等），以及如何将转换工作委托给远程 docling-serve API 服务并配置本地回退。读完后你将掌握：MCP 客户端的最小接入配置、DOCLING_SERVICE_URL / DOCLING_CONVERSION_MODE 等远程模式环境变量、远程服务不可用时的降级策略，以及底层 REST 协议在 Docling 本仓库中的对应实现证据。

1. 为什么需要 MCP：Agentic AI 的工具接入标准

原文档开篇指出了一个趋势：AI 正在从"被动应答"走向 Agentic AI——能够在有限监督下自主理解、规划并执行特定任务的智能体系统。Agent 要真正"动手"干活，就必须能调用外部工具；而模型与工具之间的集成问题是长期痛点。

MCP（Model Context Protocol） 正是为了解决这一集成问题而兴起的主流标准：它为 AI 应用与外部工具之间提供了统一的连接协议。Docling 对这个趋势的回应是提供了一个 Docling MCP Server：把它加进任何支持 MCP 的客户端，Agent 就可以直接"实验文档处理"——即让 Agent 按自己的意图决定转换哪些文档、以什么方式输出，而不需要开发者在应用层逐个对接 API。

需要说明的是：MCP Server 本体（docling-mcp 包）位于 Docling 生态的独立 Server 仓库中，本文所引用的配置与环境变量行为以 docs/usage/mcp.md 为权威来源；而它对接的 docling-serve REST 协议，则可以在本仓库的服务客户端与 convert-remote 命令源码中得到印证，后文会展开。

2. 在 MCP 客户端中接入 Docling

原文档强调，将 Docling MCP 加入你偏好的客户端"通常只需要在配置文件里加一段条目"。标准配置如下（uvx 会自动拉取 docling-mcp 包并启动 docling-mcp-server 进程）：

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": [
        "--from=docling-mcp",
        "docling-mcp-server"
      ]
    }
  }
}

2.1 Claude Desktop

在桌面版 Claude 中，直接编辑配置文件 claude_desktop_config.json，将上面的片段写入即可（docling-mcp 仓库另提供了现成的示例配置可供参考）。

2.2 LM Studio

在 LM Studio 中，编辑 mcp.json 文件写入相应配置段；LM Studio 也提供了"一键安装"深链按钮，点击即可自动完成 MCP Server 的安装配置。

从配置方式可以看出 Docling MCP 的设计取向：它把 Docling 包装成一个自托管、进程内启动的工具服务——客户端负责拉起 uvx --from=docling-mcp docling-mcp-server 子进程，工具调用通过 MCP 标准消息协议在该进程内完成，无需任何自建 HTTP 基础设施。

3. 远程转换模式：把 Docling 转换委托给 docling-serve

3.1 本地模式与远程模式的取舍

默认情况下，Docling MCP Server 在本地执行文档转换——文档不离开本机，模型推理在运行 MCP 客户端的机器上完成。这在单机实验、隐私敏感场景下最方便。

但在以下场景，远程模式更合适：

文档量大、单机构造/计算资源不足，需要共享一个转换服务；
希望在多 Agent、多客户端之间复用同一份 GPU/服务资源；
希望把 Docling 版本升级、依赖管理集中在服务侧统一处理。

此时可以让 MCP Server 把转换委托给一个正在运行的 API server——可以是自托管的 docling-serve 实例，也可以是托管服务——只需设置三个环境变量：

export DOCLING_SERVICE_URL=https://your-docling-service.example.com
export DOCLING_SERVICE_API_KEY=your-api-key   # if the service requires one
export DOCLING_CONVERSION_MODE=remote

各变量含义：

变量	作用
`DOCLING_SERVICE_URL`	docling-serve 服务的基础 URL（本地服务默认为 `http://localhost:5001`）
`DOCLING_SERVICE_API_KEY`	服务要求的 API key（如服务以 `DOCLING_SERVE_API_KEY` 开启了鉴权则必填，否则可省略）
`DOCLING_CONVERSION_MODE=remote`	声明转换模式为远程，MCP Server 不再在本地跑 Docling

3.2 故障回退：DOCLING_FALLBACK_TO_LOCAL

远程服务不可用（宕机、网络中断）时，Agent 会整体失去文档能力。为此文档给出了回退开关：

export DOCLING_FALLBACK_TO_LOCAL=true

启用后，当远程服务不可达时，MCP Server 会退回本地处理。注意原文档标注的前提：本地回退需要安装带本地依赖的 extra，即 pip install "docling-mcp[local]"——这意味着"远程为主、本地兜底"的部署需要同时具备两套运行时，读者在规划部署时应把这一依赖成本考虑在内（安装选项细节见 docling-mcp 仓库的安装说明）。

4. 远程模式背后的协议：docling-serve REST API 与仓库内实现证据

DOCLING_CONVERSION_MODE=remote 指向的"API server"，在本仓库文档中有完整定义：docs/usage/api_server/index.md 说明 docling-serve 是一个 FastAPI 服务，把 Docling 的文档转换能力以 REST API 形式暴露出来；REST API 参考（与 docling-serve v1.21.0 同步）给出了核心端点：

Endpoint	Method	用途
`/v1/convert/source`	POST	从 URL / base64 源转换（同步）
`/v1/convert/file`	POST	上传文件转换，multipart（同步）
`/v1/convert/source/async`、`/v1/convert/file/async`	POST	提交异步任务
`/v1/status/poll/{task_id}`	GET	轮询任务状态
`/v1/status/ws/{task_id}`	WebSocket	订阅任务状态
`/v1/result/{task_id}`	GET	获取已完成的结果

鉴权方式与 MCP 的 DOCLING_SERVICE_API_KEY 对应：服务端设置 DOCLING_SERVE_API_KEY 后，每个请求需携带 -H "X-Api-Key: <YOUR_KEY>"。

本仓库不仅描述了这套协议，还内置了它的官方 Python 客户端，可以直接用来验证远程服务是否按 MCP remote 模式预期的那样工作。DoclingServiceClient 的用法（来自 REST API 文档）：

from docling.service_client import DoclingServiceClient
from docling.datamodel.service.options import ConvertDocumentsOptions

with DoclingServiceClient(url="http://localhost:5001") as client:
    result = client.convert(
        source="https://arxiv.org/pdf/2501.17887",
        options=ConvertDocumentsOptions(to_formats=["md"]),
    )

print(result.document.export_to_markdown())

从源码结构看，客户端的实现细节进一步印证了远程模式的工程完备性（见 docling/service_client/client.py）：

客户端默认优先使用 WebSocket 订阅任务状态（StatusWatcherKind.WEBSOCKET），并可通过 ws_fallback_to_poll 回退到轮询——这正解释了 REST API 同时提供 /status/ws/ 与 /status/poll/ 两条状态通道的意义；
默认并发 DEFAULT_MAX_CONCURRENCY = 8（上限 512）、默认任务超时 300 秒、HTTP 重试 3 次（client.py#L127-L131），这些是长时间文档转换的合理缺省值；
client.py 中还有针对产物下载地址的 SSRF 防护（_is_safe_artifact_url，client.py#L149-L180），拒绝把预签名 URL 指向内网地址——说明该客户端是面向生产环境的严肃实现，而非演示代码。

仓库还提供了可直接运行的示例：docs/examples/service_client/README.md 说明这些脚本针对已运行的 docling-serve 实例工作（pip install "docling-slim[service-client]" 安装客户端），并通过 DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY 环境变量或工作目录的 .env 文件定位服务；convert.py 演示了 convert()（单文档）与 convert_all(source=[...], max_concurrency=4)（并发批量）两个高层 API，其默认行为（OCR、表格结构、Markdown 输出）与本地 DocumentConverter 保持一致。

4.1 同一套环境变量约定：`docling convert-remote` CLI

一个值得注意的交叉印证：本仓库 CLI 中的 docling convert-remote 命令使用与 MCP remote 模式完全相同的环境变量名。docling/cli/remote.py 的帮助文本明确写道：

Authentication (precedence: flag > environment variable > .env file):
  --service-url      or  DOCLING_SERVICE_URL     (required)
  --api-key          or  DOCLING_SERVICE_API_KEY (optional; omit if unauthenticated)
  A .env file in the working directory is loaded automatically when present.

即：命令行 flag 优先于环境变量，环境变量优先于 .env 文件；服务不可达时退出码为 1，配置错误（如未解析到任何 service URL）时退出码为 2（remote.py#L58-L61）。这带来两个实操价值：

配置可复用：为 MCP Server 配好的 DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY 环境变量，可以直接被 CLI 和 Python 示例脚本（convert.py 等）复用，同一部署环境只维护一份凭据；
协议可验证：如果你不确定 MCP remote 模式背后调用的服务是否健康，可以用同环境下的 docling convert-remote report.pdf --to md 或示例脚本做一次端到端冒烟测试，命令内部会先调用 client.health() 快速失败（见 remote.py#L343-L346），再执行转换并复用与本地 convert 完全相同的导出器，输出格式一致。

此外，convert-remote 的参数集（--from/--to、--no-ocr、--page-range、enrichment 开关等）恰好对应 REST API 文档中 options 字段的"公共子集"（to_formats、do_ocr、page_range、do_picture_description 等），可以从中反推出远程转换时你能通过服务侧控制哪些行为——注意其中没有本地执行类参数（device、线程数、PDF 后端内部选项等），因为这些只在本地运行时才有意义（remote.py#L4-L10 的模块 docstring 明确说明了这一取舍）。

5. 面向特定框架的 Agent 工具与生态示例

原文档还指出：Docling MCP 针对一些应用和框架提供了专用工具（tools），并给出了一批"用 Docling 能力构建 Agent"的示例方向，涵盖 LlamaIndex、Llama Stack、Pydantic AI、smolagents 等流行框架。具体工具清单与示例代码以 docling-mcp Server 仓库为准；本仓库侧可结合的资料包括集成指南目录（LangChain、LlamaIndex、Haystack 等）与服务客户端示例（其中 tasks.py 演示任务生命周期与结果目标，chunk.py 演示把文档切分为检索就绪的 chunks）。

可以推断：MCP 是"协议层"的统一入口（任何 MCP 客户端都能用），而框架示例解决的是"编程层"的集成——两条路径互补，前者适合桌面/对话式 Agent 快速实验，后者适合把 Docling 嵌入自有 Python 服务。

6. 选型与落地建议

结合 API server 文档的选型表，可以给出清晰的分层建议：

你的场景	推荐路径
在 Claude Desktop / LM Studio 等客户端里让 Agent 本地处理文档	Docling MCP，默认本地模式，只需一段 `mcpServers` 配置
多客户端/多 Agent 共享一个转换服务	Docling MCP + `DOCLING_CONVERSION_MODE=remote` 指向自托管 docling-serve（见部署文档）
不想运维基础设施	指向托管服务（如 Docling for IBM watsonx，见 managed service 说明），只需替换 base URL 并提供 API key
Python 应用内直接调用（非 Agent 场景）	`DoclingServiceClient`（客户端代码）或 `docling convert-remote` 命令
远程服务要有可用性兜底	MCP remote 模式 + `DOCLING_FALLBACK_TO_LOCAL=true`（需 `docling-mcp[local]` extra）

安全方面提醒：DOCLING_SERVICE_API_KEY 属于凭据，文档示例将其写入 shell 导出或 .env 文件是常规做法，但不应提交进版本库；服务端鉴权由 DOCLING_SERVE_API_KEY 控制，请求侧以 X-Api-Key 头传递。

小结

Docling 对 Agentic AI 的接入方案是分层清晰的：MCP Server 提供协议统一，让任意 MCP 客户端一行配置即可让 Agent 获得文档理解工具；本地/远程双模式（DOCLING_CONVERSION_MODE）加本地回退（DOCLING_FALLBACK_TO_LOCAL）覆盖从单机实验到共享服务再到高可用兜底的完整谱系；而远程模式的底层 docling-serve REST 协议在本仓库有完整的文档（API server）、示例（service_client 示例）与生产级客户端实现（docling/service_client/）作为支撑，DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY 环境变量在 MCP Server、convert-remote CLI 和 Python 示例间保持一致，是同一套远程接入约定的不同投影。