Run Docling as a service — docling-serve, the API and MCP

Start a server in one minute#

pip install "docling-serve[ui]"
docling-serve run --enable-ui          # API: http://127.0.0.1:5001 · docs: /docs · UI: /ui

docker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 \
  quay.io/docling-project/docling-serve-cpu

docling-serve run listens on all interfaces (host 0.0.0.0); docling-serve dev binds to 127.0.0.1 and auto-reloads for development. Image choice and GPU variants are on the Docker page.

How a request flows#

Endpoints#

Paths read from docling_serve/app.py in 1.38.2. Management endpoints (/v1/clear/*, /v1/memory/*) exist but are off unless DOCLING_SERVE_ENABLE_MANAGEMENT_ENDPOINTS is set.

Convert a URL#

curl -X POST http://localhost:5001/v1/convert/source \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
    "options": {"to_formats": ["md", "json"], "do_ocr": false}
  }'

The response is a ConvertDocumentResponse: document (with md_content, json_content, html_content, text_content, doctags_content for the formats you asked for), status, errors, processing_time, timings and confidence.

Source kinds accepted in 2.143.1's request model: http, file (base64), s3, azure_blob, google_cloud_storage and google_drive.

Upload a file#

curl -X POST http://localhost:5001/v1/convert/file \
  -F 'files=@report.pdf' \
  -F 'to_formats=md' \
  -F 'do_ocr=false' \
  -F 'table_mode=fast'

Options become form fields with the same names as in the JSON body; repeat a field for lists (-F to_formats=md -F to_formats=json). The config builder writes these requests for you.

Long documents: async jobs#

import time, requests

BASE = "http://localhost:5001"
job = requests.post(f"{BASE}/v1/convert/source/async", json={
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
    "options": {"to_formats": ["md"]},
}).json()

task_id = job["task_id"]
while True:
    status = requests.get(f"{BASE}/v1/status/poll/{task_id}").json()
    if status["task_status"] in ("success", "partial_success", "failure"):
        break
    time.sleep(2)

result = requests.get(f"{BASE}/v1/result/{task_id}").json()
print(result["document"]["md_content"][:300])

Options you will actually use#

The JSON options object is ConvertDocumentsOptions. The most common fields and their defaults in 2.143.1:

Server settings#

All settings are environment variables with the DOCLING_SERVE_ prefix (or a YAML/JSON file given by DOCLING_SERVE_CONFIG_FILE). Uvicorn settings use UVICORN_.

Defaults read from docling_serve/settings.py (1.38.2).

Python clients#

Docling ships its own client. It mirrors DocumentConverter, so switching between local and remote conversion is a one-line change.

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

with DoclingServiceClient(url="http://localhost:5001") as client:   # api_key="..." if set
    result = client.convert(
        "https://arxiv.org/pdf/2408.09869",
        options=ConvertDocumentsOptions(do_ocr=False, to_formats=["md"]),
    )
    print(result.document.export_to_markdown()[:300])

Install it without PyTorch via pip install "docling-slim[service-client]"; the same extra adds the docling convert-remote command (see the CLI reference).

MCP: Docling for AI agents#

docling-mcp exposes conversion and document tools to MCP clients such as Claude Desktop or LM Studio. In version 3.x the default conversion mode is remote, so point it at a docling-serve instance — or install the local extra.

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": ["--from=docling-mcp", "docling-mcp-server"],
      "env": {
        "DOCLING_MCP_CONVERSION_MODE": "remote",
        "DOCLING_MCP_SERVICE_URL": "http://localhost:5001"
      }
    }
  }
}

uvx --from "docling-mcp[local]" docling-mcp-server --transport stdio
# with DOCLING_MCP_CONVERSION_MODE=local in the environment

Transports: stdio (desktop clients), sse and streamable-http (containers). docling-mcp 3.x requires MCP SDK 2.x; pin docling-mcp<3.0.0 for clients that have not migrated.

Production checklist#

• Set DOCLING_SERVE_API_KEY and restrict DOCLING_SERVE_CORS_ORIGINS.
• Use the async endpoints for anything over a few pages; sync calls are capped at 120 s.
• Cap input with DOCLING_SERVE_MAX_NUM_PAGES and DOCLING_SERVE_MAX_FILE_SIZE.
• Pre-download models into the image (DOCLING_SERVE_ARTIFACTS_PATH) so pods start without internet.
• Scale out with DOCLING_SERVE_ENG_KIND=rq and Redis workers when one machine is not enough.

Frequently asked questions

Sources

• docling-serve 1.38.2 source: app.py, settings.py, auth.py
• docling-serve documentation
• docling 2.143.1: ConvertDocumentsOptions (docling/datamodel/service/options.py)
• docling-mcp 3.3.0 README