The docling-mcp server enables text-only LLMs to process documents and images by providing these capabilities:
Convert to Markdown: Transform PDF, DOCX, PPTX, HTML, or images into Markdown with tables, image placeholders, and optional VLM-generated descriptions. Supports configurable caption modes (skip, OCR text, VLM description), page range selection, and OCR language override.
Convert to Plain Text: Extract clean, linearized text (tables become text) from documents/images. Useful for token-limited models. Also supports page range and OCR languages.
Extract Tables: Retrieve structured table data, including page number, dimensions, Markdown representation, and row-major cell values.
Chunk for RAG: Segment documents into overlapping chunks with metadata (page, headings, token count) using docling’s HybridChunker. Configurable chunk size, overlap, and HuggingFace tokenizer.
Flexible Input: Accepts local file paths, HTTP(S) URLs, or Base64 data URIs.
OCR & VLM Integration: Uses OCR engines (RapidOCR, EasyOCR) for scanned content; optionally enhances images with an OpenAI-compatible VLM for rich descriptions (falls back to OCR-only if unavailable).
Deployment: Can run over stdio for local MCP clients (e.g., Claude Desktop, Cursor) or HTTP for remote integrations (e.g., DeepSeek). Configurable via environment variables (file size limits, OCR languages, VLM settings, etc.).
Enables using an OpenAI-compatible vision-language model (e.g., GPT-4o-mini) to generate image descriptions for documents, producing richer Markdown output when VLM is enabled.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docling-mcp Convert the PDF at https://arxiv.org/pdf/2408.09869 to markdown"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
把 docling 封装成 MCP 服务器,让纯文本大模型(DeepSeek 等)通过工具调用获得"文档视觉"。
docling 是 IBM 开源的高质量文档解析库(PDF / DOCX / PPTX / HTML / 图片),支持 OCR、表格识别、公式抽取、版面分析。但它只提供 Python API。本包把它包成 MCP(Model Context Protocol)服务器,暴露 4 个工具,任何 MCP 客户端都能调用。
DeepSeek-v4 / pro 这类纯文本模型看不了 PDF、图片、扫描件。挂上 docling-mcp 后,模型可以调用工具:
解析 PDF → Markdown 喂回自己
把图片里的文字 OCR 出来
抽出表格结构化数据
把文档切片做 RAG
工具 | 用途 | 输出 |
| PDF/DOCX/HTML/图片 → Markdown(含表格、图片占位) |
|
| 同上 → 纯文本(无格式标记,适合 token 受限的模型) | string |
| 只抽表格 |
|
| 用 HybridChunker 切片做 RAG |
|
| 真正理解图片(物体/场景/图表/动作),不是只 OCR 文字 |
|
所有工具的第一个参数 source 都支持:
本地路径:"E:/docs/report.pdf"
HTTP(S) URL:"https://arxiv.org/pdf/2408.09869"
Data URI:"data:application/pdf;base64,JVBERi0xLjQ..."(适合远端 HTTP 客户端上传二进制)
cd E:/ideadatabase/py_data/agent_coding/docling-mcp
pip install -e .
# 首次运行会自动下载 docling 模型(约 500MB,可能慢)docling 首次启动要从 HuggingFace Hub 拉约 500MB 模型,直连 huggingface.co 通常失败。本包已内置如下规避策略,只需在 .env 或环境变量中配置:
DOCLING_MCP_HF_ENDPOINT=https://hf-mirror.com # 走 HF 镜像
DOCLING_MCP_HF_BYPASS_PROXY=true # 强制绕过本地代理(Clash 等常导致 SSL 错误)__init__.py 在导入 HF 库之前会读取这两个变量并:
设置 HF_ENDPOINT=https://hf-mirror.com
设置 HF_HUB_DISABLE_XET=1(关掉 Xet,否则权重文件仍走 us.aws.cdn.hf.co 直连失败)
清空 HTTP_PROXY / HTTPS_PROXY 等代理变量,设置 NO_PROXY=*(本地 VPN 代理常对 hf-mirror 做 MITM 触发 SSL EOF)
如果镜像仍报超时,手动预热模型(推荐用 Python API 而非 huggingface-cli,Windows GBK 控制台对 CLI 不友好):
# 在能上 HF 的机器或 VPN 上跑
python -c "from huggingface_hub import snapshot_download; \
snapshot_download('docling-project/docling-layout-heron'); \
snapshot_download('BAAI/bge-small-en-v1.5')"
# 然后把 ~/.cache/huggingface 拷到目标机器或下载到自定义位置:
HF_HOME=E:/hf_cache python -c "from huggingface_hub import snapshot_download; \
snapshot_download('docling-project/docling-layout-heron')"转换失败时,工具会返回带可操作提示的错误信息(检查 error 字段)。
docling 支持多 OCR 引擎,本包按以下优先级自动选择:
RapidOCR(默认,推荐)—— onnxruntime 后端,无 torch 依赖,体积小,已通过 docling 自带安装。
EasyOCR —— torch 后端,语言覆盖广,需 pip install easyocr。
docling 默认 —— 上述都失败时使用。
切换为 EasyOCR:pip install easyocr,然后代码会自动用上(见 converter.py:_build_pipeline_options)。
复制 .env.example 为 .env,按需修改:
DOCLING_MCP_OCR_LANGS=en,zh # 默认 OCR 语言
DOCLING_MCP_VLM_URL=... # 可选:OpenAI 兼容 VLM 端点
DOCLING_MCP_VLM_API_KEY=...
DOCLING_MCP_VLM_MODEL=gpt-4o-mini
DOCLING_MCP_VLM_ENABLED=false # 默认禁用,工具入参 enable_vlm 可临时开OCR 只提取图片里的文字,不理解图片内容。describe_image 通过一个视觉语言模型(VLM)真正"看"图:识别物体、场景、人物、图表含义。
免费方案:智谱 GLM-4V-Flash(OpenAI 兼容,国内直连):
# 到 https://open.bigmodel.cn 注册获取 API key
DOCLING_MCP_VLM_URL=https://open.bigmodel.cn/api/paas/v4/chat/completions
DOCLING_MCP_VLM_API_KEY=你的智谱key
DOCLING_MCP_VLM_MODEL=glm-4v-flash配置好后,直接让模型描述图片:
# 本地图片
curl ... "describe_image" ... "arguments":{"source":"E:/photos/receipt.png","prompt":"这张图里有什么?"}
# 网络图片
curl ... "describe_image" ... "arguments":{"source":"https://example.com/photo.jpg"}支持任意 OpenAI 兼容视觉端点,不限于智谱。未配置时工具返回清晰的错误提示。
python -m docling_mcp # 默认 stdio
# 或
docling-mcp编辑 claude_desktop_config.json(macOS: ~/Library/Application Support/Claude/,Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"docling": {
"command": "docling-mcp",
"env": {
"DOCLING_MCP_OCR_LANGS": "en,zh"
}
}
}
}类似配置,使用 docling-mcp 命令作为 MCP server。
DOCLING_MCP_TRANSPORT=http DOCLING_MCP_PORT=8765 python -m docling_mcp
# 或
docling-mcp-http测试:
curl -X POST http://127.0.0.1:8765/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"convert_to_text",
"arguments":{"source":"https://arxiv.org/pdf/2408.09869"}}
}'DeepSeek 当前不直接支持 MCP,但你可以:
把本服务跑在 HTTP 模式
在你的应用代码里,用 DeepSeek 的 function-calling 接口,把 4 个工具描述注册为 functions
当 DeepSeek 决定调用工具时,你用 HTTP 转发到本 MCP,把结果作为 user message 注入对话
参考 examples/deepseek_bridge.py(若存在)。
Related MCP server: doc-ingestor-mcp
Wraps docling as an MCP server. Text-only LLMs (DeepSeek v4/pro, etc.) gain document vision by calling these tools.
convert_to_markdown(source, [ocr_languages], [enable_vlm], [page_range], [image_caption_mode]) → {markdown, ...}
convert_to_text(source, [ocr_languages], [page_range]) → string
extract_tables(source, [ocr_languages]) → [{page, index, num_rows, num_cols, markdown, rows}, ...]
chunk_for_rag(source, [chunk_size=1024], [overlap=100], [tokenizer], [ocr_languages]) → [{text, index, page, headings, ...}, ...]
describe_image(source, [prompt]) → {description, model, prompt_tokens, completion_tokens} — semantic image understanding via a VLM (not just OCR text). Requires DOCLING_MCP_VLM_URL/API_KEY/MODEL. Free option: Zhipu glm-4v-flash at https://open.bigmodel.cn/api/paas/v4/chat/completions.
source accepts local path, HTTP(S) URL, or data: URI.
pip install -e .First run downloads docling models (~500MB).
python -m docling_mcp # stdio (default, for Claude Desktop / Cursor)
python -m docling_mcp http # streamable-http (for remote LLMs)Var | Default | Purpose |
|
| transport mode |
|
| http host |
|
| http port |
|
| comma-separated OCR langs |
| (empty) | OpenAI-compatible chat completions URL |
| (empty) | VLM bearer key |
|
| VLM model name |
|
| global VLM default |
|
| per-file size cap |
| (empty) | HuggingFace mirror, e.g. |
|
| drop local proxy env vars before HF imports |
pip install -e .[dev]
pytest tests/ -vUnit tests (sources normalization) run without docling. Smoke tests skip if docling is not installed.
src/docling_mcp/
├── __main__.py CLI entrypoint, stdio/http switch
├── server.py FastMCP + 4 @mcp.tool() functions
├── converter.py DocumentConverter singleton, asyncio.Lock, optional VLM pipeline
├── sources.py path/URL/data-URI normalization → local file
├── config.py pydantic-settings env config
└── schemas.py Pydantic models for tool I/OKey design choices:
Lazy init — DocumentConverter (loads torch + models) only built on first call.
Lock-serialized — concurrent tool calls share one converter under a global lock.
VLM graceful degradation — tries multiple docling API shapes; falls back to OCR-only on failure and emits a warnings field.
Three input modes — local path, HTTP(S) URL, base64 data URI; unified to a (Path, cleanup) handle.
MIT
Chunk a document for RAG using docling's HybridChunker.
Returns list of {text, index, page, headings, chunk_type, token_count}.
Args: source: Local path / URL / data URI. chunk_size: Target max tokens per chunk. overlap: Overlap tokens between adjacent chunks. tokenizer: HuggingFace tokenizer name. Defaults to BGE-small (English). Use a multilingual tokenizer (e.g. "bert-base-multilingual-cased") for non-English docs. ocr_languages: Override default OCR languages.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| overlap | No | ||
| tokenizer | No | BAAI/bge-small-en-v1.5 | |
| chunk_size | No | ||
| ocr_languages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return format (list of dicts with fields), the default tokenizer, and provides guidance for multilingual documents. It does not explicitly state whether the operation is read-only or requires network access for tokenizer downloads, but it covers the most important behavioral aspects for a chunking tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a clear first line, a return format line, and a clean Args block. Every sentence adds value; there is no redundancy or fluff. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough for an agent to invoke the tool correctly: it covers the tool's purpose, return values, and all parameters with defaults and usage notes. It lacks error-handling or edge-case details, but these are not critical for a chunking tool. The output schema is not shown, but the return format is explicitly described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains all five parameters: source (path/URL/data URI), chunk_size, overlap, tokenizer (with default and multilingual hint), and ocr_languages (as override). The only gap is that ocr_languages is underspecified (no details on format or acceptable values), but overall it adds substantial meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Chunk') and resource ('a document for RAG'), and explicitly mentions using docling's HybridChunker. It distinguishes itself from sibling tools like convert_to_text and extract_tables by focusing on chunking rather than conversion or extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context: chunking for RAG. It implicitly signals when to use this tool (when chunks are needed for retrieval), but it does not explicitly mention alternatives or exclusion criteria. However, the purpose is specific enough that an agent would know to use it for chunking rather than the conversion siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a document or image to Markdown.
Supports PDF, DOCX, PPTX, HTML, and image files (PNG/JPG/etc.).
Args: source: Local path, HTTP(S) URL, or data URI (data:;base64,...). ocr_languages: Override default OCR languages, e.g. ["en","zh"]. Defaults to env. enable_vlm: If True and a VLM endpoint is configured, generate richer image descriptions via an OpenAI-compatible API. Falls back to OCR text if unavailable. page_range: Optional (start, end) 1-indexed inclusive page range for PDFs. image_caption_mode: How to represent pictures in markdown: - "skip": placeholder only - "ocr_text": picture's OCR'd text (default) - "vlm_description": VLM-generated description (requires enable_vlm)
Returns: ConvertMarkdownResult as dict: {markdown, num_pages, num_tables, num_pictures, source_type, warnings}.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| enable_vlm | No | ||
| page_range | No | ||
| ocr_languages | No | ||
| image_caption_mode | No | ocr_text |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does excellently: it discloses VLM fallback behavior, OCR language override default, page_range inclusivity, and the return result structure. This goes beyond basic facts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-sentence purpose, supported formats, then a detailed Args section and Returns section. Every sentence adds value, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, 1 required, output schema), the description covers all inputs, explains behavioral nuances, and even describes the return result fields. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description thoroughly explains each of the 5 parameters, including default values, formats, and meaning (e.g., enable_vlm, page_range, image_caption_mode with its enumerated options). This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts a document or image to Markdown, listing specific supported formats (PDF, DOCX, PPTX, HTML, images). This distinguishes it from siblings like convert_to_text and extract_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what formats and options are supported, and how opts like page_range and image_caption_mode work. However, it does not explicitly compare with siblings (e.g., when to use convert_to_text instead), so it lacks direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a document or image to plain text (no markdown formatting).
Best for feeding token-limited text-only LLMs. Tables are linearized. Returns just the text string.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| page_range | No | ||
| ocr_languages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly states output is just a text string without markdown, and that tables are linearized. This adds useful behavioral context beyond the schema. However, it does not mention how page_range or ocr_languages affect behavior, which is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with zero waste. The purpose is stated first, followed by use case and key behavioral notes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained, and the description does mention the return type. It covers purpose, use case, and a transformation detail. However, it does not describe how the optional parameters work or what happens when an image vs document is provided, making it slightly incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fails to explain page_range or ocr_languages. The only hint is 'document or image' which loosely maps to the 'source' parameter, but provides no detail on format, defaults, or constraints. This is a significant gap for a three-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Convert') with a clear resource ('document or image') and output type ('plain text'). It explicitly distinguishes itself from sibling tools by noting 'no markdown formatting' and 'tables are linearized', differentiating it from convert_to_markdown and extract_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Best for feeding token-limited text-only LLMs.' This implies when to use this tool, though it does not explicitly mention alternatives or when not to use it. The sibling tool list helps, but the description could be more direct about when markdown or chunking would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract all tables from a document.
Returns a list of {page, index, num_rows, num_cols, markdown, rows}.
Each rows entry is a list of cell strings (row-major).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| ocr_languages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses the exact return contract (list of page, index, num_rows, num_cols, markdown, rows) and clarifies row structure. It does not address potential side effects or performance, but as a read-only extraction tool the output contract is the most relevant behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the action, and uses a compact structured list for the return shape. Every sentence adds useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters and no annotations, and the description covers the core extraction behavior and output shape. However, it omits semantics for source and ocr_languages, and does not explain when to prefer this over convert_to_markdown or convert_to_text, leaving integration gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implies 'source' refers to a document but does not explain accepted formats (path, ID, content). The ocr_languages parameter is completely unexplained, leaving a required part of the invocation ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Extract all tables from a document', a specific verb+resource that clearly distinguishes from sibling tools like convert_to_text or convert_to_markdown. It also specifies the produced data structure, reinforcing the tool's table-focused purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool vs alternatives. The phrase 'Extract all tables' implies a use case (need structured table data), but it does not mention sibling conversion tools, exclusions, or preconditions such as OCR requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0chunk_for_ragconvert_to_markdownconvert_to_textextract_tablesScored across 4 tools
Each tool has a clearly distinct purpose: plain text conversion, markdown conversion, table extraction, and RAG chunking. No two tools overlap in function, and the descriptions clarify the differences even between the two conversion tools.
All tool names follow a consistent verb_noun pattern in snake_case (convert_to_text, convert_to_markdown, extract_tables, chunk_for_rag). The naming is uniform and predictable.
With 4 tools, the server is well-scoped for document processing. Each tool covers a distinct need without redundancy, and the number is within the ideal range.
The server covers the primary conversion and extraction needs (text, markdown, tables) plus chunking for RAG. Minor gaps exist, such as direct document structure extraction or image extraction, but agents can work around these using the provided tools.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
DocBase MCP server for AI agents
