Getting started with pdfmcp

Three ways to use pdfmcp — free web tools that run on your device, and the local package for AI agents and code (MCP server, local REST API and Python library) — each set up in about a minute. No account, no key, free forever.

Three ways to use pdfmcp

pdfmcp is one toolbox with three entrances, and all of them are on your side of the wire. The web tools on this site run in your browser, on your device — your file is never uploaded, and there is no sign-up. The local package installs the same 74 operations on your own machine as an MCP server for AI agents (Claude, Cursor, VS Code and more), as a local REST API you serve yourself (pdfmcp serve, on localhost), and as a Python library for your own scripts.

All three are free — free forever. There is no paid tier, no watermark, no trial clock, no account and no API key. Usage is unlimited because your device does the work; the only limits are your machine's memory and storage.

Way 1: Use a web tool (no sign-up)

Open the tool index and pick what you need — merge, split, compress, convert, OCR, sign, redact and more. Tools marked “On-device” process your file entirely in this browser tab: drop the file in, set the options, and download the result. Nothing is transmitted to us, so there is nothing to store, log or leak.

A few operations need heavier machinery than a browser tab should carry (full OCR to a searchable PDF, Office conversion, some cryptography). Those pages are marked “Local package” and show you how to run the same operation with the package below — still on your machine, still with no upload.

Way 2: Install the local package

One package, everything included — there are no tiers or extras to unlock:

pip install https://pdfmcp.org/downloads/pdfmcp-4.2.1-py3-none-any.whl

That installs the `pdfmcp` command: a local MCP server (stdio transport) that any MCP client on your machine can launch. The package starts small. The first time a tool needs a heavy engine, pdfmcp downloads it once from the engine's official upstream release, verifies its SHA-256, and caches it on your machine: qpdf (about 4 MB) and the Tesseract OCR language data work this way. Ghostscript and the Tesseract program itself ship only as system installers, so if they're missing the tool tells you the exact install command for your platform instead of failing silently. LibreOffice — needed only for Office-to-PDF conversion — is likewise a system install; everything else runs without it.

Connect the MCP server to your AI agent

Most clients accept this config shape — it launches the local server with uvx, which fetches the package for you, so there is nothing to install by hand:

{"mcpServers": {"pdfmcp": {"command": "uvx", "args": ["--from", "https://pdfmcp.org/downloads/pdfmcp-4.2.1-py3-none-any.whl", "pdfmcp"]}}}

Restart your client after editing its config; the pdfmcp tools then appear in its tool list, and every call executes on your machine. There are step-by-step setup guides for 13 clients — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed, Cline, Continue, JetBrains and any other MCP client — linked from the MCP page. One honest exception: ChatGPT can't run local servers (its connectors are remote-only), so inside ChatGPT there is no pdfmcp — use the web tools, or a local-capable client.

Use it from your own code

The same engine is a Python library on your machine. Install the package, build the local runtime, and call operations with base64-encoded files; jobs execute synchronously, in-process, and results come back inline as base64:

from app.local_main import build_local_runtime from app.config import Settings import base64

rt = build_local_runtime(Settings(storage_dir="~/.pdfmcp/files")) result = rt.run_sync("compress", {}, [base64.b64encode(open("report.pdf", "rb").read()).decode()])

Prefer plain HTTP, or a language other than Python? Run pdfmcp serve: the package starts a local REST API on 127.0.0.1:8765 (localhost only by default) backed by that same local runtime — GET /healthz, GET /v1/operations, POST /v1/jobs (multipart), GET /v1/jobs/<id> and GET /v1/jobs/<id>/result. No account, no API key needed, no quotas, and your files never leave your machine.

The MCP surface mirrors this: each operation is a tool taking files_b64, the async trio (submit_job, get_job_status, get_job_result) executes synchronously in the local edition, and a pipeline tool chains operations so each step's output feeds the next. The full walkthrough, with a complete curl example, is the Local API quickstart guide.

Limits, privacy and the honest edges

There are no quotas to hit: no daily allowance and no hourly cap — pdfmcp has no shared server to ration. The practical limits are your device's: a 400-page conversion can strain a phone, and the tools apply their own sanity checks (for example, the web tools note a 100 MB working guideline bounded by browser memory).

Privacy is architectural. Web tools never receive your file at all — processing happens in your browser. The local package processes files on your machine, has no telemetry and never phones home; its only network traffic is the one-time verified engine downloads described above, which you can disable. Nothing you process is used to train AI models; there is no copy of it anywhere but your device. The only analytics on this website are page-hit counts and Google Analytics — see the analytics page for exactly what is collected.

The honest edges: metadata tools strip metadata-layer provenance (C2PA, EXIF, XMP), but pixel-embedded watermarks such as SynthID live in the image data itself and no metadata tool removes them — our pages say so instead of pretending. And conversion quality is engine-bound: local conversions use LibreOffice-class engines where LibreOffice is installed, the same class most rivals use, so we will not claim prettier Word files than anyone else.

Connect your AI agent — the free local MCP server

Frequently asked questions

Is pdfmcp really free?

Yes — free forever. All 74 tools are included in the web tools and the one local package. There is no paid tier, no watermark and nothing to unlock.

Do I need an account?

No. There are no pdfmcp accounts and no API keys, for anything. Web tools never need an account, and the local package runs with no sign-in.

Where do my files go?

Nowhere. Web tools process your file in your browser; the local package processes it on your machine. Files never leave your device, and nothing is used for AI training.

Can I use pdfmcp offline?

Yes. Once a web tool's page and libraries are loaded it needs no server, and the local package runs entirely on your machine — the only downloads are the one-time engine fetches on first use, which you can disable.

Why do some web pages say “Local package”?

A few operations need heavy engines (full OCR, Office conversion) that don't belong in a browser tab. They run in the local package on your machine instead — same operation, same privacy: no upload.

Can ChatGPT use pdfmcp?

Not directly: ChatGPT's connectors are remote-only and pdfmcp has no remote server. Use the web tools in your browser, or a local-capable client such as Claude, Cursor or VS Code.