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
Claude Desktop venv (recommended)
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_venvso Docling stays on the VM under/mnt. Override withCLAUDE_VENVif 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.