emperor-pdf

emperor-pdf

[CI] [license] [Glama]

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 ondocker 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-<os>-<cpu>.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=<n> 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-onlyemperor-pdf serve --root ~/Documents/papers --pdfium-dir ./pdfium
# also offer pdf_pages and pdf_create, and allow saving rendered pagesemperor-pdf serve --root ~/Documents/papers --pdfium-dir ./pdfium --writable
# stdio, for clients that start the server themselvesemperor-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 stdioclaude 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 (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 warnings are framed as computed values.
• Markdown cannot run code. pdf_create escapes every character of text and passes code and links as string literals, so Markdown cannot reach Typst as markup or script; the Typst world serves no file but the generated one, and fonts are embedded, so a document cannot read the disk. Typst runs only on a writable server built with the create feature.
• Bounded work. Files over 256 MiB are refused, fallback text extraction caps decompressed content per page, renders are capped at 300 dpi and 8000 px a side, Markdown input at 2 MiB.

doctor

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

emperor-pdf 0.1.3 doctor  [ok  ] root folder     /Users/me/Documents/papers (writable)  [ok  ] pdfium          loaded from ./pdfium/lib/libpdfium.dylib  [ok  ] typst fonts     6 embedded faces (DejaVu Sans Mono, Libertinus Serif)  [ok  ] listen address  127.0.0.1:8032 is free  [ok  ] tool budget     6 of at most 8 toolsall good (0 warning(s))

It exits 1 when a check fails. A missing PDFium is a warning, not a failure. --stdio skips the port check. The tool budget counts the tools the server would list: four read-only, six with --writable. The fonts check is absent from a --no-default-features build.

Develop

scripts/fetch-pdfium.sh        # once, so the PDFium tests run instead of being skippedcargo fmt --all --checkcargo clippy --all-targets -- -D warningscargo clippy --all-targets --no-default-features -- -D warningscargo testcargo deny check

The tests build their fixture PDFs with Typst in a temporary folder and talk to a real server over HTTP (and one over stdio); url sources are fetched from a small local HTTP server. The tool lists are checked with emperor-mcp's testkit. Without ./pdfium the PDFium-only tests print a note and pass.

Links

• crates.io: emperor-pdf
• Official MCP Registry: mcp-name: io.github.yarenty/emperor-pdf
• Framework: emperor-mcp
• How it compares with other PDF MCP servers: docs/COMPARISON.md

Licence

Dual licensed under MIT OR Apache-2.0, at your option.

Fonts

With the create feature the binary embeds two font families for pdf_create, from assets/fonts with their licence texts:

Both are permissive and allow embedding in documents and redistribution with software. No GPL-licensed font is included (Typst's own New Computer Modern set is not used). Release archives carry both licence texts as FONTS-NOTICE. Documents you create are not affected by these licences beyond keeping the font's own notices if you extract the font. PDFium, when you install it, is under its own licences (Apache-2.0 / BSD-3-Clause).