Skip to main content

pdf-porter

Layout-aware PDF to Markdown for Claude — one tool, zero config, five minutes to set up. Uses Docling to preserve tables, multi-column layouts, and document structure that Claude's native PDF ingestion loses.

If you want the full Docling toolset, see docling-mcp by IBM Research. pdf-porter is intentionally minimal: one tool, one job.

Installation

Install pdf-porter into a dedicated venv so Docling and its weights live in one place (no uv global cache, no project path in config):

cd pdf-porter
./scripts/setup_claude_desktop_venv.sh
  • macOS: venv is ~/Library/Application Support/Claude/venv.
  • Linux / VM: venv defaults to /mnt/claude_venv so Docling stays on the VM under /mnt. Override with CLAUDE_VENV if needed.

The script prints the exact config snippet. Add it and restart Claude Desktop. First tool call will download Docling weights (~500MB); subsequent calls are fast.

Use with uvx (simple, uses uv cache)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-tools": {
      "command": "uvx",
      "args": ["pdf-porter"]
    }
  }
}

Then restart Claude Desktop.

Project-managed install (development / testing)

To keep Docling and its weights in this repo only (no uv global cache):

cd pdf-porter
uv sync

Then point Claude Desktop at the repo’s script so the server uses this venv:

{
  "mcpServers": {
    "pdf-tools": {
      "command": "/ABSOLUTE/PATH/TO/pdf-porter/scripts/run_server.sh"
    }
  }
}

Replace /ABSOLUTE/PATH/TO/pdf-porter with the real path (e.g. "/Users/you/GitHub/pdf-porter"). Docling and weights live in the project’s .venv; you avoid cache bloat and unsatisfiable resolves from other envs.

Development

git clone https://github.com/benmazzotta/pdf-porter
cd pdf-porter
uv sync --dev
uv run pytest

Tool Reference

pdf_to_markdown

Parameter Type Default Description
path str — Path to a PDF on the server’s filesystem
pdf_base64 str — Base64-encoded PDF bytes (use for uploads; see below)
save_output bool False If True, writes a .md file and returns the output path
output_dir str — Directory for the .md file when save_output=True (e.g. /mnt/user-data/outputs/)
filename str — Original filename hint for base64 mode (e.g. "report.pdf" → output is "report.md")

You must pass either path or pdf_base64 (not both). Paths under /mnt/user-data/uploads/ (e.g. Claude Desktop uploads) are not visible to the server; for those, pass the file content as pdf_base64 instead.

Returns: Markdown string, or a bare output file path when save_output=True, or "Error: <message>" on failure.

Known Limitations

  • First run: Docling downloads model weights (~500MB). You'll see a pause. Subsequent runs are fast.
  • Scanned PDFs: OCR mode is not enabled in v0.1. Image-only PDFs will return empty or minimal text.
  • Windows: Path handling not validated on Windows.

License

MIT. See LICENSE.

Metadata

Release files for pdf-porter 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pdf-porter 0.3.0
File Size Uploaded Provenance Actions
pdf_porter-0.3.0.tar.gz 179.9 kB Without provenance Details for pdf_porter-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pdf-porter 0.3.0
File Interpreter ABI Platform Actions
pdf_porter-0.3.0-py3-none-any.whl Python 3 none any Details for pdf_porter-0.3.0-py3-none-any.whl

Total release size: 185.5 kB

Release files / pdf_porter-0.3.0.tar.gz

Download URL pdf_porter-0.3.0.tar.gz
Size 179.9 kB
Tags Source
SHA-256 checksum
How to use checksums
17a3e3aeaa0ef62394da4fb02aad5825520a8a57b2ed05fb73b76903c7036ec6
BLAKE2b-256 checksum
How to use checksums
006229e109648b7c8a1999bb0b6c2e31e416c2879951bbc4eb7c574e31a136af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / pdf_porter-0.3.0-py3-none-any.whl

Download URL pdf_porter-0.3.0-py3-none-any.whl
Size 5.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
560ee22d0759c197dace95ce66b497a18f76458eca72a5be095f224c921cef74
BLAKE2b-256 checksum
How to use checksums
62e45ddf6b32945ae5d4f32a56721859acf09d643f0a007b5875fe96d6367156
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for pdf-porter 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page