pdf-mcp

An MCP server that exposes Marker — high-quality PDF OCR and conversion — as a tool for MCP clients like Claude Code and Claude Desktop.

One tool: convert_pdf(path, output_dir?, page_range?, output_format?, use_llm?). It writes the converted markdown/JSON/HTML plus extracted images to a folder (default: <name>_marker/ next to the PDF) and returns the output path with stats. Results are never returned inline — read the output file.

Requirements

• Python ≥ 3.10 and uv

• ~5GB disk: Marker's models (~3GB, downloaded from HuggingFace on first conversion) plus torch. First conversion of a session takes 30+ seconds while models load; later conversions are much faster.

Install

git clone https://github.com/Xander-git/pdf-mcp && cd pdf-mcp
uv sync

Claude Code

claude mcp add pdf-mcp -- uv --directory /absolute/path/to/pdf-mcp run pdf-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/pdf-mcp", "run", "pdf-mcp"]
    }
  }
}

LLM-enhanced mode (optional)

Pass use_llm=true to improve complex tables, inline math, and forms using Gemini. Requires GOOGLE_API_KEY in the server's environment, costs API credits, and sends page content to Google. Everything else runs fully local.

Setting up a Gemini API key

1. Create an API key at Google AI Studio (free tier available).

2. Provide it to the server as the GOOGLE_API_KEY environment variable:

Claude Code — pass it when registering the server:

claude mcp add pdf-mcp --env GOOGLE_API_KEY=your-key-here -- uv --directory /absolute/path/to/pdf-mcp run pdf-mcp

Claude Desktop — add an env block to the server entry:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/pdf-mcp", "run", "pdf-mcp"],
      "env": { "GOOGLE_API_KEY": "your-key-here" }
    }
  }
}

Licensing

• This package is licensed GPL-3.0-or-later. It links against marker-pdf, which is GPL-3.0-or-later; as a derivative work, pdf-mcp carries the same license.

• Model weights (Surya/Marker models, downloaded at runtime from HuggingFace — never redistributed by this repo) are licensed by Datalab under a modified OpenRAIL-M: free for research, personal use, and startups under $2M funding/revenue. Broader commercial use requires a Datalab license.

This project is intended for personal use. If you fork it for commercial use, review both licenses above.