Docling MCP

Docling MCP：让 Docling 具备 Agent 能力

一个使用 Docling-MCP 库和 MCP（模型上下文协议）进行工具集成的文档处理服务。

概览

Docling MCP 是一项服务，提供用于文档转换、处理和生成的工具。它使用 Docling 库将 PDF 文档转换为结构化格式，并提供缓存机制以提升性能。该服务通过一组工具向客户端应用程序开放功能，供其调用。

兼容性

docling-mcp	MCP Python SDK
>=3.0.0	mcp>=2.0.0
>=2.0.0,<3.0.0	mcp>=1.9.4,<2.0.0

如果你的 MCP 客户端应用程序尚未迁移到 MCP SDK v2，请固定版本：

pip install "docling-mcp<3.0.0"

完整迁移指南请参阅 MIGRATION.md。

安装选项

远程模式（推荐 - 轻量级）

适用于可访问 Docling Serve API 的用户：

获取 Docling Serve：访问 docling-serve 查看安装指南。你可以通过已发布的容器镜像进行部署，也可以寻找托管的 Docling SaaS 服务。

pip install docling-mcp

然后配置环境：

export DOCLING_MCP_SERVICE_URL=https://your-docling-service.example.com
export DOCLING_MCP_SERVICE_API_KEY=your-api-key-here
export DOCLING_MCP_CONVERSION_MODE=remote

本地模式（完整功能）

适用于需要本地转换或无法访问 Docling Serve 的用户：

pip install docling-mcp[local]

然后配置环境：

export DOCLING_MCP_CONVERSION_MODE=local

混合模式（两全其美）

安装本地支持并启用自动回退：

pip install docling-mcp[local]

配置为使用远程模式并启用回退：

export DOCLING_MCP_SERVICE_URL=https://your-docling-service.example.com
export DOCLING_MCP_CONVERSION_MODE=remote
export DOCLING_MCP_FALLBACK_TO_LOCAL=true

功能

• 转换工具：
  • 将 PDF 文档转换为结构化 JSON 格式（DoclingDocument）
• 生成工具：
  • 以 DoclingDocument 格式生成文档，并可导出为多种格式
• 本地文档缓存，提升性能
• 支持将本地文件和 URL 作为文档来源
• 内存管理，用于处理大型文档
• 用于调试和监控的日志系统
• 支持使用 Milvus 上传和检索的 RAG 应用

配置

所有设置均使用 DOCLING_MCP_ 前缀，可通过环境变量、工作目录中的 .env 文件，或 MCP 客户端配置中的 env 块提供。复制 .env.example 作为起点。

转换模式

变量	默认值	描述
DOCLING_MCP_CONVERSION_MODE	remote	remote 或 local

远程服务（DOCLING_MCP_CONVERSION_MODE=remote 时必需）

变量	默认值	描述
DOCLING_MCP_SERVICE_URL	—	Docling Serve 实例的 URL
DOCLING_MCP_SERVICE_API_KEY	—	服务的 API 密钥
DOCLING_MCP_SERVICE_TIMEOUT	300.0	整个转换任务的超时时间，单位为秒
DOCLING_MCP_SERVICE_MAX_RETRIES	3	最大重试次数
DOCLING_MCP_FALLBACK_TO_LOCAL	false	服务无法访问时回退到本地（需要 docling-mcp[local]）

转换管线（适用于两种模式）

变量	默认值	描述
DOCLING_MCP_KEEP_IMAGES	false	在输出中保留页面图像
DOCLING_MCP_IMAGES_SCALE	1.0	图像缩放系数（增大此值可避免张量填充错误）
DOCLING_MCP_DO_OCR	true	运行 OCR 管线
DOCLING_MCP_DO_TABLE_STRUCTURE	true	检测表格结构
DOCLING_MCP_DO_PICTURE_DESCRIPTION	false	运行视觉语言模型，为图表和图片生成文本描述
DOCLING_MCP_PICTURE_DESCRIPTION_PRESET	—	图片描述 VLM 的预设 ID（例如 smolvlm、granite_vision）。未设置时使用后端默认值。仅在 DOCLING_MCP_DO_PICTURE_DESCRIPTION=true 时生效

提示

启用 DOCLING_MCP_DO_PICTURE_DESCRIPTION=true 后，文档中的每个图表都会增加一个 VLM 推理步骤。在资源受限的硬件上（例如在笔记本电脑上使用 CPU 运行模型），这会显著增加转换时间。

• 远程模式 — 增大 DOCLING_MCP_SERVICE_TIMEOUT（单位为秒），为远程服务留出足够的完成时间。默认值为 300.0（5 分钟）。
• 本地模式 / MCP 客户端超时 — MCP 客户端本身也可能会强制执行请求超时。例如，在 LM Studio 中，可在 mcp.json 中设置 timeout 字段（单位为毫秒）：

{
  "mcpServers": {
    "docling": {
      "url": "http://localhost:8000/mcp",
      "timeout": 300000
    }
  }
}

Markdown 导出

变量	默认值	描述
DOCLING_MCP_IMAGE_EXPORT_MODE	placeholder	Markdown 输出中图像的呈现方式：placeholder（输出 ``）、embedded（base64 数据 URI）、referenced（文件路径 / URL）

缓存

变量	默认值	描述
DOCLING_MCP_CACHE_MAX_DOCUMENTS	10	内存缓存中保留的最大文档数。达到上限时，将移除最近最少使用的文档。

LlamaIndex RAG（--tools llama-index-rag）

变量	默认值	描述
DOCLING_MCP_LI_API_BASE	http://127.0.0.1:1234/v1	与 OpenAI 兼容的大模型端点
DOCLING_MCP_LI_API_KEY	none	大模型端点的 API 密钥
DOCLING_MCP_LI_MODEL_ID	ibm/granite-3.2-8b	大模型标识符
DOCLING_MCP_LI_EMBEDDING_MODEL	BAAI/bge-base-en-v1.5	HuggingFace 嵌入模型

LlamaStack（--tools llama-stack-rag / --tools llama-stack-ie）

变量	默认值	描述
DOCLING_MCP_LLS_URL	http://localhost:8321	LlamaStack 服务 URL
DOCLING_MCP_LLS_VDB_EMBEDDING	all-MiniLM-L6-v2	向量数据库的嵌入模型
DOCLING_MCP_LLS_EXTRACTION_MODEL	openai/gpt-oss-20b	用于结构化提取的模型

在 MCP 客户端配置中设置变量

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": [
        "--from=docling-mcp",
        "docling-mcp-server"
      ],
      "env": {
        "DOCLING_MCP_CONVERSION_MODE": "remote",
        "DOCLING_MCP_SERVICE_URL": "https://your-docling-service.example.com",
        "DOCLING_MCP_SERVICE_API_KEY": "your-api-key-here"
      }
    }
  }
}

入门

安装 Docling MCP 并将其连接到客户端，最简单的方式是通过 uvx 启动。

根据所需的传输协议，指定参数 --transport，例如：

• stdio，例如用于 Claude for Desktop 和 LM Studio

  uvx --from docling-mcp docling-mcp-server --transport stdio
  

• sse，例如用于 Llama Stack

  uvx --from docling-mcp docling-mcp-server --transport sse
  

• streamable-http，例如用于容器设置

  uvx --from docling-mcp docling-mcp-server --transport streamable-http
  

还有其他选项，例如选择要启动的工具组。使用 --help 参数查看所有 CLI 选项。

如需进一步开发 MCP 工具，请参阅 CONTRIBUTING.md 中的 开发 部分，了解相关说明。

与 MCP 客户端集成

试用 Docling MCP 提供的工具，最简单的方式之一是使用支持 MCP 的 AI 桌面客户端。 大多数此类客户端都使用通用配置接口。要在你常用的客户端中添加 Docling MCP，通常只需在配置文件中添加以下条目。

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

使用 Claude for Desktop 时，只需编辑配置文件 claude_desktop_config.json，并加入上面的代码片段或此处提供的示例。

在 LM Studio 中，编辑 mcp.json 文件并添加相应部分，或直接点击下方按钮进行安装。

其他集成方式请参阅 [集成] 页面。

示例

转换文档

转换 PDF 文档的提示词示例：

Convert the PDF document at <provide file-path> into DoclingDocument and return its document-key.

生成文档

生成新文档的提示词示例：

I want you to write a Docling document. To do this, you will create a document first by invoking `create_new_docling_document`. Next you can add a title (by invoking `add_title_to_docling_document`) and then iteratively add new section-headings and paragraphs. If you want to insert lists (or nested lists), you will first open a list (by invoking `open_list_in_docling_document`), next add the list_items (by invoking `add_list_items_to_list_in_docling_document`). After adding list-items, you must close the list (by invoking `close_list_in_docling_document`). Nested lists can be created in the same way, by opening and closing additional lists.

During the writing process, you can check what has been written already by calling the `export_docling_document_to_markdown` tool, which will return the currently written document. At the end of the writing, you must save the document and return me the filepath of the saved document.

The document should investigate the impact of tokenizers on the quality of LLMs.

贡献

欢迎外部贡献。请参阅 CONTRIBUTING.md，了解如何开始。

许可证

Docling MCP 代码库采用 MIT 许可证。有关各个模型的使用，请参阅原始软件包中的模型许可证。

LF AI & Data

Docling 和 Docling MCP 是 LF AI & Data Foundation 下的一个项目。

IBM ❤️ 开源 AI：该项目由 IBM Research Zurich 的 AI for knowledge 团队发起。