Read PDF bytes, list local PDFs, and display/interact with PDFs via @modelcontextprotocol/server-pdf (npx) — official Anthropic reference server

Recipe: Read PDF bytes and metadata via @modelcontextprotocol/server-pdf over stdio

Package: @modelcontextprotocol/server-pdf v1.7.4 (official Anthropic reference server) Transport: stdio (MUST pass --stdio flag; default is HTTP on port 3001) Entry point: node node_modules/@modelcontextprotocol/server-pdf/dist/index.js --stdio Tools exposed: 8 total (3 user-facing, 1 raw-access, 4 viewer-internal) Auth: none required

Setup

npm install --prefix /tmp/mcp-pdf @modelcontextprotocol/server-pdf

MCP Client Connection

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: [
    "/tmp/mcp-pdf/node_modules/@modelcontextprotocol/server-pdf/dist/index.js",
    "--stdio",
    "/tmp/test.pdf"  // local files as positional CLI args
  ]
});
const client = new Client({ name: "pathfinder", version: "1.0" });
await client.connect(transport);

Tools

Headless-only recipe (readpdfbytes)

For headless/stdio usage, read_pdf_bytes is the ONLY useful tool. It accepts:

• url (string) — HTTPS URL to a PDF, OR a local file path registered via CLI arg
• offset (number, optional) — byte offset for pagination
• Max 512KB per request

Gotchas

1. MUST pass `--stdio` — without it, the server starts an HTTP server on port 3001. This conflicts with reserved ports and isn't MCP stdio transport.
2. Local files must be registered via CLI args — passing a local path to read_pdf_bytes that wasn't listed as a positional CLI arg returns "not in allowed list."
3. `display_pdf` + `interact` require Claude Desktop/claude.ai viewer — in headless stdio mode, these time out after ~8 seconds with "Viewer never connected." This is expected behavior, not a bug.
4. `interact` has 14 sub-actions but ALL need the viewer — get_text, annotate, search_text, fill_form, get_form_fields, get_page_count, go_to_page, zoom, scroll, get_selection, get_annotations, delete_annotation, get_bookmarks, get_metadata. None work headless.
5. URL PDFs work dynamically — you don't need to register URLs via CLI; read_pdf_bytes({url: "https://..."}) works for any accessible HTTPS URL.
6. Default URL is arxiv 1706.03762 (Attention Is All You Need) — used when no URL is specified.
7. 404 URLs return graceful isError — no crash, clean error message.
8. Pagination via offset works — first call returns bytes + total size, subsequent calls with increasing offsets read the rest.

Verified trace (11 calls across 2 sessions)

Session 1 (6 calls):

1. list_pdfs({}) — returned list of registered PDFs including the CLI-arg local file
2. read_pdf_bytes({url:"https://arxiv.org/pdf/1706.03762"}) — 512KB chunk of Attention paper, 149ms
3. read_pdf_bytes({url:"https://arxiv.org/pdf/1706.03762", offset:524288}) — second chunk, 47ms
4. read_pdf_bytes({url:"/tmp/test.pdf"}) — local 586-byte PDF, full content in one read
5. read_pdf_bytes({url:"https://example.com/nonexistent.pdf"}) — isError, graceful 404
6. display_pdf({url:"https://arxiv.org/pdf/1706.03762"}) — timeout after 8019ms, "Viewer ne