PDF Card MCP

PDF Card MCP

PDF Card MCP is a local-first MCP server and CLI for turning dense local PDFs into portable, source-linked HTML readers. An MCP host can ask it to convert a PDF path, validate notes/highlights, or publish a static annotated reader bundle. The converter preserves source text, renders source pages for verification, crops detected tables, figures, and display formulas as images, derives safe reader styling from the original PDF palette, and writes a standalone HTML file that can be moved across devices without losing assets.

Default conversion runs locally and does not require a hosted service. Optional MCP sampling is deliberately bounded: the host model may choose validated style tokens or suggest card-boundary polish operations, but raw CSS and source-text rewrites are rejected.

The default reader is designed for comfortable reading: large type, small cards, search, section navigation, next/previous controls, keyboard navigation, a font-size slider, and source-page previews.

PDF Card MCP is meant for PDFs you actually need to read, cite, or inspect. It turns long documents into smaller source-linked cards, keeps tables/figures/formulas as faithful image crops, and lets you export your own notes and highlights as Markdown.

Quick Install (one-click)

PDF Card MCP is a Python server, so it needs a runtime. The one thing to install first is uv — it manages Python for you, so you do not have to. This is the only prerequisite for every install path below:

# macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then add the server with one click. The buttons run the published pdf-card-mcp package through uv:

Claude Code (terminal):

claude mcp add pdf-card -- uvx --from pdf-card-mcp pdf-card-mcp-server

Claude Desktop (no terminal, no prerequisites): download pdf-card-mcp-desktop.mcpb from the latest release and double-click it to install as an extension. This bundle declares the uv runtime, so Claude Desktop installs Python and dependencies for you — you do not need the uv step above for this path.

After installing, restart (or reload MCP servers in) your client so it picks up the new server.

Real Screenshots

These screenshots are from a generated reader for *Agents in Software Engineering* and the same source PDF opened side by side for comparison.

Quick Examples

Convert a local PDF into one portable HTML reader:

pdf-card-mcp ./paper.pdf --output ./out/paper-reader.html

Use the explicit subcommand form with PDF-derived styling:

pdf-card-mcp convert ./paper.pdf \

--output ./out/paper-reader.html \ --style-engine pdf

Run the MCP server so a compatible host can generate readers from local PDF paths:

python -m pdf_card_mcp.server

Publish a read-only static reader with selected public annotations:

pdf-card-mcp publish ./out/paper-reader.html \

--annotations ./paper.annotations.json \ --output ./published/paper-reader.html

Output At A Glance

Status

This is an early open-source implementation. It is useful for text-layer PDFs now, with best-effort table detection via pdfplumber, permissive raster rendering via pypdfium2, and optional richer local table detection via gmft. Scanned PDFs need optional OCR support.

Install

Most people should use the one-click install above. To install the package directly instead, from PyPI:

python -m pip install pdf-card-mcp

Or install the latest unreleased changes directly from the repository:

python -m pip install "pdf-card-mcp @ git+https://github.com/velyan/pdf-card-mcp.git"

For local development:

git clone https://github.com/velyan/pdf-card-mcp.git

cd pdf-card-mcp python3 -m venv .venv . .venv/bin/activate python3 -m pip install -e ".[dev]"

uv is recommended for MCPB packaging:

uv sync

uv run pdf-card-mcp path/to/document.pdf --output out/document.html

Install the optional local ML table detector when you want stronger table crops:

uv sync --extra table-ml

uv run --extra table-ml pdf-card-mcp path/to/document.pdf --table-engine gmft

Use In An MCP Client

Add it to Claude Code or another CLI-compatible MCP client with uvx (requires uv):

claude mcp add pdf-card -- uvx --from pdf-card-mcp pdf-card-mcp-server

Generic MCP host configuration:

{

"mcpServers": { "pdf-card": { "command": "uvx", "args": ["--from", "pdf-card-mcp", "pdf-card-mcp-server"] } } }

For local development before the PyPI release, point the client at this checkout:

{

"mcpServers": { "pdf-card-local": { "command": "uv", "args": [ "--directory", "/path/to/pdf-card-mcp", "run", "python", "-m", "pdf_card_mcp.server" ] } } }

Claude Desktop can also install the .mcpb bundle from the latest GitHub release.

Docker / Registry Scanners

The repository includes a minimal Dockerfile so registries such as Glama can build the server, start it over stdio, and inspect its MCP tool schemas. The server still works on local file paths, so container users must mount any PDFs and output directories they want the tool to read or write:

docker build -t pdf-card-mcp .

docker run --rm -i \ -v "$PWD/examples:/docs" \ pdf-card-mcp

CLI Usage

pdf-card-mcp path/to/document.pdf --output examples/out/document.html

The command writes:

• document.html: standalone reader with embedded CSS, JavaScript, table crops, figure crops, formula crops, and source-page images.
• document.manifest.json: structured metadata without embedded image payloads.

The explicit subcommand form is also supported:

pdf-card-mcp convert path/to/document.pdf --output examples/out/document.html

Notes, Highlights, And Static Publishing

Generated readers include a local annotation overlay:

• A highlight is selected source text.
• A note is selected source text plus your own typed note text.

Select text in a text card, choose Highlight or Note, and use Export Markdown to download a readable .annotations.md file. Import is intentionally not exposed in the reader UI yet. Notes and highlights are user-authored data and are kept separate from the source-derived document.manifest.json.

The lower-level CLI and MCP publishing tools still accept a structured annotation bundle when you need to build a read-only static reader with embedded annotations. Validate that bundle against a reader:

pdf-card-mcp validate-annotations examples/out/document.html document.annotations.json

Publish a shareable static reader with public annotations:

pdf-card-mcp publish examples/out/document.html \

--annotations document.annotations.json \ --output published/document-reader.html

If --output is a directory instead of an .html file, the command writes a static bundle:

• index.html
• reader.manifest.json
• reader.annotations.json
• bundle.json

Publishing includes only visibility: public annotations by default, redacts the local source_pdf path by default, and renders the published reader read-only by default. Use --include-private only when you intentionally want private local notes included in the published output. Publishing fails if any included annotation cannot be anchored to the reader; run validate-annotations to inspect mismatches before publishing.

MCP Tool

The MCP server is the automation layer around the same local converter. It accepts local file paths from an MCP client and returns generated reader paths, manifest metadata, warnings, and publishing/validation results.

The server exposes three tools:

convert_pdf_to_card_html

validate_reader_annotations publish_reader_bundle

Inputs:

• pdf_path: local PDF path.
• output_path: optional HTML output path.
• title: optional title override.
• standalone: defaults to true; asset-folder output is reserved for a later release.
• ocr: optional OCR fallback if pytesseract is installed.
• max_pages: optional processing limit.
• theme: defaults to soft.
• style_engine: fixed, pdf, or sampling; defaults to pdf. fixed preserves the original soft palette, pdf derives bounded colors and typography hints locally from the source PDF, and sampling asks the host LLM to choose validated style tokens from those local hints.
• table_engine: auto, pdfplumber, or gmft; auto uses gmft when installed.
• text_engine: char_geometry or pdfplumber_words; defaults to char_geometry so missing spaces are repaired from PDF character positions instead of trusting fused words.
• postprocess_engine: none or sampling; defaults to none. When set to sampling, the MCP server asks the host LLM for boundary-only card polish operations, validates exact source-text preservation, and rewrites the generated reader. If the MCP client does not support sampling, deterministic output is returned with a warning.
• model_cache_dir: optional cache directory for local ML table model weights.

-