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-<os>-<cpu>.tgz from a release yourself and unpack it anywhere. The

... View full README on GitHub