# pdf-mcp

An MCP server that exposes [Marker](https://github.com/datalab-to/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](https://docs.astral.sh/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

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

### Claude Code

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

### Claude Desktop

Add to `claude_desktop_config.json`:

```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](https://aistudio.google.com/apikey) (free tier available).
2. Provide it to the server as the `GOOGLE_API_KEY` environment variable:

**Claude Code** — pass it when registering the server:

```bash
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:

```json
{
  "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](LICENSE). It links against
  [marker-pdf](https://github.com/datalab-to/marker), 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](https://www.datalab.to/).

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