velyan/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:
Then add the server with one click. The buttons run the published
pdf-card-mcp package through uv:
**Claude Code** (terminal):
**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.
| Generated reader | Original PDF |
| --- | --- |
| | |
| | |
Quick Examples
Convert a local PDF into one portable HTML reader:
Use the explicit subcommand form with PDF-derived styling:
Run the MCP server so a compatible host can generate readers from local PDF paths:
Publish a read-only static reader with selected public annotations:
Output At A Glance
| Output | What it contains |
| --- | --- |
| paper-reader.html | Standalone reader with embedded CSS, JavaScript, page images, and detected crops. |
| paper.manifest.json | Structured metadata for cards, pages, warnings, and source anchors. |
| Markdown export | User-authored notes and highlights from the reader UI. |
| Published bundle | Read-only static HTML or a directory bundle for sharing public annotations. |
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:
Or install the latest unreleased changes directly from the repository:
For local development:
uv is recommended for MCPB packaging:
Install the optional local ML table detector when you want stronger table crops:
Use In An MCP Client
Add it to Claude Code or another CLI-compatible MCP client with uvx (requires
uv):
Generic MCP host configuration:
For local development before the PyPI release, point the client at this checkout:
Claude Desktop can also install the .mcpb bundle from the latest GitHub release.