Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pymupdf/pymupdf4llm-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Docker gives you a self-contained, reproducible environment for pymupdf4llm-mcp with no host Python installation required. The repository ships a production-ready Dockerfile that builds a slim image based on Python 3.12, uses uv for fast, deterministic dependency installation, and supports both stdio and SSE transport modes via the command passed at runtime.

​
The Dockerfile

The repository ships with a production-ready Dockerfile. Here is the full contents: 
# Install uv
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Change the working directory to the `app` directory
WORKDIR /app

# Copy the lockfile and `pyproject.toml` into the image
COPY uv.lock /app/uv.lock
COPY pyproject.toml /app/pyproject.toml

# Install dependencies
RUN uv sync --frozen --no-install-project

# Copy the project into the image
COPY . /app

# Sync the project
RUN uv sync --frozen

ENTRYPOINT [ "tini", "--", "uv", "run", "pymupdf4llm_mcp"]
CMD ["stdio"]
Key design decisions:
  • Base image: python:3.12-slim keeps the image small while providing a supported Python runtime.
  • Dependency manager: uv is copied from its own official image, giving fast, lock-file-based installs.
  • Entrypoint: tini acts as PID 1, ensuring clean signal handling and proper zombie-process reaping inside the container.
  • Default command: stdio — override it at docker run time to switch to SSE mode.

​
Building the Image

Clone the repository and build the image with a memorable tag: 
docker build -t pymupdf4llm-mcp .
There is no pre-built image published to Docker Hub or any other registry. You must build the image from the repository source using the command above.

​
Running the Container

SSE mode is the most practical choice for Docker because it exposes a stable HTTP endpoint that survives container restarts and can be reached from the host or other containers. Bind to 0.0.0.0 inside the container so that Docker’s port mapping works correctly: 
docker run -p 3000:3000 pymupdf4llm-mcp sse --host 0.0.0.0 --port 3000
The server is now reachable at http://localhost:3000/sse from the host machine.

​
Mounting a Local PDF Directory

By default the container has no access to files on your host. Use a volume mount (-v) to share a directory of PDFs with the container. Files placed in that directory become available at the mount point inside the container: 
docker run -p 3000:3000 \
  -v /path/to/pdfs:/data \
  pymupdf4llm-mcp sse --host 0.0.0.0 --port 3000
When calling the convert-pdf-to-markdown tool, pass the in-container path — for example /data/document.pdf — as the file_path argument.
PDF file paths must be accessible inside the container, not on the host. If you pass a host path like /Users/me/report.pdf the container will not find it and the tool call will fail. Always use volume mounts (-v) to expose the files you need, then reference them by their container-side path (e.g. /data/report.pdf).

​
Connecting an MCP Client

Once the container is running in SSE mode, configure your MCP client to connect to it the same way as any other SSE server: 
{
  "mcpServers": {
    "pymupdf4llm-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}
Update the url if you mapped the container to a different host port.

​
Running in stdio Mode Inside Docker

For CI/CD pipelines or one-shot automation jobs you may prefer stdio mode. The container reads from stdin and writes to stdout, just like a locally installed binary: 
docker run --rm -i \
  -v /path/to/pdfs:/data \
  pymupdf4llm-mcp stdio
The --rm flag removes the container automatically after it exits, keeping your environment clean. The -i flag keeps stdin open so the MCP client can communicate with the process.

Build docs developers (and LLMs) love

Get started for freeTalk to us