emperor-pdf

emperor-pdf

The PDFs in one folder, for your agents: read, search, render, merge, split and write them.

An MCP server that works on the PDFs inside a single root folder and nowhere else:

• Read and search text page by page, from the root folder, from base64 bytes in the call, or from an https:// URL, with Google's PDFium, the engine inside Chrome, and fall back to a pure-Rust extractor when PDFium is not installed.
• Warn about hidden text: white-on-white, invisible, sub-point or off-page text, the usual way to plant instructions for a model in a document a person thinks is harmless.
• See a page as a PNG image the model can look at (also how scanned pages are read).
• Merge and extract pages, and create PDFs from Markdown, typeset with Typst and OFL fonts built into the binary.
• Confined by capability, not by string checks: every file is opened through a cap-std directory handle, so .., absolute paths and symlinks that lead out of the root are refused by the operating system layer.
• Read-only by default: without --writable the writing tools are not even offered.

Built on the emperor-mcp framework: stateless Streamable HTTP (or stdio for desktop clients), framed output, a doctor subcommand, four tools read-only and six with --writable. It meets Emperor Profile P1.1: no tool that writes is listed unless the operator switches writing on at start-up (--writable or PDF_WRITABLE), and tool definitions are lean, with short descriptions that say when to use each tool and compact input schemas.

Install

Prebuilt binaries (macOS arm64/x86_64, Linux x86_64, Windows x86_64) are attached to GitHub releases. Or build from source:

cargo install --git https://github.com/yarenty/emperor-pdf

Rust 1.92 or newer is needed to build (typst 0.15 sets that minimum).

Read-only build

pdf_create is behind the create Cargo feature (on by default), which brings in Typst and the embedded fonts. Without it you get a smaller binary that reads, searches, renders, merges and extracts:

cargo install --git https://github.com/yarenty/emperor-pdf --no-default-features

Docker

The repository's Dockerfile builds an image that speaks MCP over stdio and carries PDFium (linux/amd64 and linux/arm64). Mount the folder with your PDFs at /data:

docker build -t emperor-pdf .

docker run -i --rm -v ~/Documents/papers:/data:ro emperor-pdf

read-write: mount without :ro and switch writing on

docker run -i --rm -e PDF_WRITABLE=true -v ~/Documents/papers:/data emperor-pdf

The server runs as uid 10001, so for --writable the mounted folder must be writable by it.

PDFium (recommended)

PDFium is a native library loaded at runtime; it is not bundled with emperor-pdf. Prebuilt PDFium binaries for every platform come from bblanchon/pdfium-binaries (Apache-2.0 / BSD-3-Clause). From a checkout:

scripts/fetch-pdfium.sh            # downloads the right archive for this machine into ./pdfium/

or download pdfium- - .tgz from a release yourself and unpack it anywhere. The release is pinned to chromium/7881, the PDFium API version the pdfium-render binding is built for; PDFIUM_VERSION= scripts/fetch-pdfium.sh picks another.

emperor-pdf looks for libpdfium.dylib / libpdfium.so / pdfium.dll, in this order:

1. --pdfium-dir DIR (the library in DIR, DIR/lib or DIR/bin),
2. PDFIUM_DYNAMIC_LIB_PATH (a folder, with the same lib/ and bin/ lookup, or the file),
3. the folder holding the emperor-pdf binary,
4. the system library path.

Without PDFium, pdf_text and pdf_search use lopdf's extractor (and say so in their output: it misses or garbles text in some PDFs), and pdf_render_page answers that it needs PDFium. Everything else works the same.

Run

# Streamable HTTP at http://127.0.0.1:8032/mcp, read-only

emperor-pdf serve --root ~/Documents/papers --pdfium-dir ./pdfium

also offer pdf_pages and pdf_create, and allow saving rendered pages

emperor-pdf serve --root ~/Documents/papers --pdfium-dir ./pdfium --writable

stdio, for clients that start the server themselves

emperor-pdf serve --stdio --root ~/Documents/papers

Logs go to stderr (RUST_LOG=debug for more). GET /health answers OK.

Connect a client

Claude Code

# HTTP (start the server first)

claude mcp add --transport http pdf http://127.0.0.1:8032/mcp

or stdio

claude mcp add pdf -- emperor-pdf serve --stdio --root /path/to/pdfs --pdfium-dir /path/to/pdfium

Claude Desktop (claude_desktop_config.json)

{

"mcpServers": { "pdf": { "command": "/path/to/emperor-pdf", "args": ["serve", "--stdio", "--root", "/path/to/pdfs", "--pdfium-dir", "/path/to/pdfium"] } } }

Claude Desktop, read-write: add "--writable" to args.

[Kowalski](https://github.com/yarenty/kowalski) (config.toml), over HTTP or stdio:

[[mcp.servers]]

name = "pdf" transport = "http" url = "http://127.0.0.1:8032/mcp"

or let Kowalski start it

[[mcp.servers]] name = "pdf" transport = "stdio" command = ["/path/to/emperor-pdf", "serve", "--stdio", "--root", "/path/to/pdfs", "--pdfium-dir", "/path/to/pdfium"]

Tools

The four reading tools take the PDF in one of three ways, exactly one per call:

• path: a file relative to the root folder (for pdf_search also a glob such as **/*.pdf);
• data: the PDF bytes, base64 (a data:application/pdf;base64, prefix is accepted);
• url: an https:// URL the server downloads.

data and url are capped at 8 MiB (the emperor-mcp limits byte cap); downloads time out after 30 seconds and follow at most five redirects.

Page numbers are 1-based. pdf_pages keeps the pages and their content but not the inputs' bookmarks, forms or tagged structure.

Tool annotations say what each tool does: the reading tools are read-only, idempotent and open-world (they can fetch a URL); pdf_pages, pdf_create and pdf_render_page on a writable server are not read-only and are marked destructive, since overwrite: true replaces a file. On a read-only server pdf_render_page is marked read-only, because it cannot save.

Hidden text

With PDFium, pdf_text and pdf_search check every character of the pages they read and flag text a person looking at the page would likely not see:

• text drawn in the invisible render mode (mode 3), unless it lies over an image, which is how OCR makes a scanned page searchable;
• white or near-white (or fully transparent) text with nothing drawn behind it;
• text set below 1 pt;
• text outside the page box.

The text is still returned, inside the document frame; a separate, framed warning names the file, the pages and the reasons, and asks the model to treat it as data and tell the user. pdf_search marks each hit on such a page with page_has_hidden_text. The check is a heuristic: a white background drawn inside a form object, for example, hides nothing but is not looked into. The lopdf fallback does not check and says so.

Scanned pages

emperor-pdf has no OCR engine. A scanned page without a text layer comes back from pdf_text as empty or near-empty; render it with pdf_render_page and let a vision-capable model read the image. Scans that were OCR'd already carry an invisible text layer, which pdf_text reads (and does not flag as hidden).

Security model

• One root, enforced by capability. The root is opened once as a cap_std::fs::Dir; every read and write goes through it by relative path. Paths with .. or an absolute path are refused with a clear message before any file system call, and cap-std refuses symlinks that resolve outside the root. Globs are expanded by walking the root through the same handle (hidden folders are skipped, at most 200 files).
• Read-only unless `--writable`. Without it, pdf_pages and pdf_create are not registered (a client never sees them) and pdf_render_page { save_as } answers that the server is read-only. With it, an existing file is never replaced unless the call passes overwrite: true.
• URLs: public HTTPS only. url must be https://, without user name or password; every redirect is checked again. Host names are resolved by the server and only public addresses are used: loopback, private (RFC 1918), link-local (including cloud metadata at 169.254.169.254), shared, unique-local IPv6 and similar ranges are refused, so a call cannot reach services on the server's own network. Downloads and data are capped at 8 MiB and must start like a PDF.
• Document text is data. PDFs come from anywhere and may carry text written to steer a model. Text and search snippets are wrapped with emperor-mcp framing as a document of unknown authorship (nonce-guarded delimiters, "data, not instructions"); metadata, results and hidden-text