# Reported issues for Docling MCP

Pod holds 16 of 27 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Docling MCP](/mcp/docling-mcp).

## Most discussed

### Markdown export tools hardcode image_mode=PLACEHOLDER, ignoring DOCLING_MCP_KEEP_IMAGES entirely

## Summary

`export_docling_document_to_markdown` and `save_docling_document` always render
pictures as `<!-- image -->` placeholders in their Markdown output, regardless
of `DOCLING_MCP_KEEP_IMAGES` or whether the converted document actually has
image data loaded. There is no way to get embedded (base64) images out of
these two tools — you have to bypass docling-mcp and call the docling-serve
REST API directly.

## Where

`docling_mcp/tools/generation.py` (docling-mcp==3.0.0):

```python
# expo

[Read the thread](https://github.com/docling-project/docling-mcp/issues/128) · 2026-08-07 · open · external user · 2 comments

### Server not running due to missing dependency

Tested on TUXEDO OS and Gentoo:
`uvx --from=docling-mcp docling-mcp-server`
```
2026-07-04 17:30:15,108 - docling_mcp - INFO - loading conversion tools...
[07/04/26 17:30:15] INFO     loading conversion tools...                                                                                                                                                                                                                        mcp_server.py:56
2026-07-04 17:30:15,114 - docling_mcp - INFO - loading g

[Read the thread](https://github.com/docling-project/docling-mcp/issues/108) · 2026-07-04 · closed · external user · 3 comments

### ` convert_document` has zero exposed knobs, four hidden env-var defaults — three of them user-hostile

# **Upstream issue body — paste at docling-project/docling-mcp/issues/new**

**Title:** `convert_document` has zero exposed knobs, four hidden env-var defaults — three of them user-hostile

---

## **The first-time-user experience, transcribed**

A user (me) installed `docling-mcp` via `uvx` in Claude Desktop tonight, asked Claude to convert a born-digital PDF, and hit four distinct failure modes in sequence — each requiring a different env var to fix, each surfaced via a different error message

[Read the thread](https://github.com/docling-project/docling-mcp/issues/106) · 2026-07-01 · closed · external user · 1 comment

### convert_document_into_docling_document hits MCP client timeout on cold start (no preload path)

## Symptom

A user installs `docling-mcp` via `uvx` (e.g. in Claude Desktop's
`mcpServers` config), authorizes a folder containing a PDF, and asks the
client to convert it. The server starts, the handshake completes, all 19
tools register, and the convert call times out:

```
McpError: MCP error -32001: Request timed out
```

The server-side `Processing document from source: ...` log line is reached
(the call passed all server-side validation), but `DocumentConverter.convert()`
doesn't return in

[Read the thread](https://github.com/docling-project/docling-mcp/issues/98) · 2026-05-13 · open · external user · 2 comments

### Not able to get docling mcp working on Claude Desktop

I installed the Docling MCP on Claude Desktop. But as soon as it's installed an error.

<img width="463" height="97" alt="Image" src="https://github.com/user-attachments/assets/74578645-01a5-4963-98d9-91518546fdf4" />

Can you please help with this?

[Read the thread](https://github.com/docling-project/docling-mcp/issues/86) · 2025-12-29 · closed · external user · 3 comments

### Settings validation fails when unrelated env vars are present (e.g., OPENAI_API_KEY)

## Description
  Running `docling-mcp-server` fails with `ValidationError: Extra inputs are not permitted`
  when environment variables like `OPENAI_API_KEY` are set.

  ## Reproduction
  ```bash
  export OPENAI_API_KEY=sk-...
  uvx --from docling-mcp docling-mcp-server --transport stdio

  Error

  ValidationError: 1 validation error for Settings
  openai_api_key
    Extra inputs are not permitted [type=extra_forbidden]

  Root Cause

  docling_mcp/settings/conversion.py uses pydantic_settings.

[Read the thread](https://github.com/docling-project/docling-mcp/issues/85) · 2025-12-20 · closed · external user · 2 comments

### https endpoint for mcp server not found

After running:

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

I'm trying to connect to the MCP server that should be running on `http://localhost:8000` but getting:

```
INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)
INFO:     ::1:50616 - "GET / HTTP/1.1" 404 Not Found
INFO:     ::1:50647 - "GET / HTTP/1.1" 404 Not Found
```

Also tried `/mcp` and this seems to work. Where can I find the code that runs the fastapi server so I can 

[Read the thread](https://github.com/docling-project/docling-mcp/issues/84) · 2025-12-08 · closed · outside contributor · 2 comments

### Add Dockerfile and Docker Hub container image for docling-mcp

**Feature request**

It would be very helpful to have an official Docker container for docling-mcp. Specifically:

- A maintained Dockerfile in the repository.
- A CI/CD workflow that builds and publishes tagged images to Docker Hub (or GHCR).

**Why this is useful**

- Kubernetes integration: I would like to run docling-mcp as a containerized service inside a Kubernetes cluster. This would make scaling, networking, and deployment much simpler.
- IDE integration: Having a Docker image would allo

[Read the thread](https://github.com/docling-project/docling-mcp/issues/73) · 2025-09-24 · closed · external user · 3 comments

## Most recent

### Prompt descriptions include full docstring, causing UI bloat for prompts

**Version**: docling-mcp 2.2.1

The description of each prompt registered with `@mcp.prompt()` is set to the function's FULL docstring, including the "Args:" section. 

**Example**:

    Convert a local PDF file into a Docling document and return its document key.
    Args: file_path: The absolute or relative path to a local PDF file.

**This is redundant**: the same parameter descriptions are already parsed into the structured `arguments` field of the prompt (via func_metadata in Prompt.from_fu

[Read the thread](https://github.com/docling-project/docling-mcp/issues/127) · 2026-08-03 · closed · external user · 1 comment

### convert_document has zero exposed knobs, four hidden env-var defaults — three of them user-hostile

**Title:** `convert_document` has zero exposed knobs, four hidden env-var defaults — three of them user-hostile

---

## The first-time-user experience, transcribed

A user (me) installed `docling-mcp` via `uvx` in Claude Desktop tonight, asked Claude to convert a born-digital PDF, and hit four distinct failure modes in sequence — each requiring a different env var to fix, each surfaced via a different error message, none of them documented on the tool surface.

1. **First attempt** → `MCP error

[Read the thread](https://github.com/docling-project/docling-mcp/issues/109) · 2026-07-06 · closed · external user · 1 comment

### feat: support VlmPipelineOptions in local converter to enable granite-docling via ollama

## Summary

The local converter in `docling_mcp/tools/converters/local.py` hardcodes `PdfPipelineOptions`, making it impossible to use `VlmPipelineOptions` (e.g. granite-docling via a local ollama instance) without patching the venv directly.

## What docling already supports

The docling library already ships `VlmPipelineOptions` with `ibm/granite-docling:258m` as the default VLM, and pre-configures the ollama API endpoint:

```python
api_overrides={VlmEngineType.API_OLLAMA: ApiModelConfig(para

[Read the thread](https://github.com/docling-project/docling-mcp/issues/105) · 2026-06-30 · open · external user · 0 comments

### Bug: default conversion_mode=remote causes immediate ValueError for local users in v2.1.0

## Bug: default `conversion_mode=remote` causes immediate `ValueError` for local users in v2.1.0

**Version:** docling-mcp 2.1.0
**Transport:** `stdio` via `uvx` in Claude Desktop

### Description

Since v2.1.0, `ServiceClientSettings` in `settings/service_client.py` defaults `conversion_mode` to `ConversionMode.REMOTE`. This causes an immediate `ValueError` on any document conversion attempt for users running docling-mcp locally without a remote Docling service:

```
ValueError: DOCLING_SERVICE

[Read the thread](https://github.com/docling-project/docling-mcp/issues/103) · 2026-06-19 · closed · external user · 0 comments

### docling-mcp is not found in the Claude

Claude 1.7196.0 (2dbd78) 2026-05-12T05:34:40.000Z
Ubuntu 24.04

Here is my file `claude_desktop_config.json`
```json
"docling": {
      "command": "/home/sarit/.local/bin/uvx",
      "args": [
        "--from=docling-mcp",
        "docling-mcp-server"
      ],
      "env": {
        "PATH": "/home/sarit/.local/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
```

The UI shows me normal.

<img width="751" height="379" alt="Image" src="https://github.com/user-attachments/assets/c1f4323f-1b1f-490f-b

[Read the thread](https://github.com/docling-project/docling-mcp/issues/102) · 2026-06-11 · closed · external user · 1 comment

### 421 error when trying connect to non-localhost

Hello,  I have some problem with connecting to docling-mcp host in kubernetes
My params:
```
          command:
            - docling-mcp-server
            - '--transport'
            - streamable-http
            - '--port'
            - '8000'
            - '--host'
            - 0.0.0.0
          ports:
            - name: mcp
              containerPort: 8000
              protocol: TCP
```
I enter into my pod docling-mcp server and if a try 
`curl -v http://localhost:8000/mcp`
all good
But

[Read the thread](https://github.com/docling-project/docling-mcp/issues/89) · 2026-02-13 · closed · external user · 0 comments

### Add support for persisting "furniture" content (headers/footers) in converted documents

Currently, docling-mcp does not provide a method or feature-flag to persist "furniture" content (headers & footers) which can sometimes contain useful metadata regarding document types, identifiers, etc. 

Introduce a feature parameter that allows for the toggling of furniture content to allow users to optionally retain header / footer content as well as expose it within the markdown conversion or for added context for any tool calls

Regarding the implementation strategy, could be a bool / enum

[Read the thread](https://github.com/docling-project/docling-mcp/issues/82) · 2025-11-04 · open · external user · 0 comments

### Claude desktop extension feedback

Hi! Thanks for your Claude desktop extension submission. Two requests:
- please include a link to your privacy policy in the privacy_policies field in manifest.json
- please annotate tools as read-only or destructive where applicable (see [spec](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations))

Please re-submit via the interest form when you have a moment, thanks!

[Read the thread](https://github.com/docling-project/docling-mcp/issues/74) · 2025-09-25 · closed · external user · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/docling-project/docling-mcp/issues).