Getting Started

Prerequisite: Node.js 20+. Every server starts via npx, so no global install is needed.

Step 1 — Minimal setup (pdf-reader)

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-reader-mcp@latest"]
    }
  }
}

Works with no environment variables. Read one PDF first to confirm it is alive.

Step 2 — pdf-spec

Placing the spec corpus

Skip this step and pdf-spec cannot answer a single question. pdf-spec-mcp does not bundle the specification PDFs themselves (ISO documents may not be redistributed). You supply the original texts — fortunately, every core document is available at no cost through legitimate channels:

Source	Documents
PDF Association: Sponsored ISO standards → the ISO 32000-2 bundle	ISO 32000-2:2020 (with Errata Collection 3) + ISO TS 32001 / 32002 / 32003 / 32004
Same page → the PDF/UA bundle	ISO 14289-1:2014 (PDF/UA-1) + ISO 14289-2:2024 (PDF/UA-2) + ISO TS 32005
Adobe's public copy, PDF32000_2008.pdf	ISO 32000-1:2008 (PDF 1.7)

The sponsored editions are genuine ISO documents published at no cost by the PDF Association, funded by sponsors including Adobe, Apryse and Foxit — free, but in no way bootleg. Put the downloaded PDFs in one directory and point PDF_SPEC_DIR at it in the pdf-spec-mcp configuration; files are then recognized by name pattern (e.g. PDF32000_2008.pdf, ISO_32000-2_2020...pdf, ISO-14289-1-2014-sponsored.pdf — 17 documents).

Setting PDF_SPEC_DIR

{
  "mcpServers": {
    "pdf-spec": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
      "env": { "PDF_SPEC_DIR": "/path/to/pdf-specs" }
    }
  }
}

WARNING

PDF_SPEC_DIR is required. This corpus is the very ground of PDF Agent Stack's normative knowledge — clauses can be quoted with full force (T1) precisely because the original text is at hand. ISO 19005 (PDF/A) and ETSI PAdES are outside the corpus — check coverage.gaps in list_specs to see what cannot be looked up.

/plugin and where each host writes the path

Even after /plugin install pdf-spec-mcp@shuji-bonji, write PDF_SPEC_DIR as an absolute path in the host's own config. The plugin's plugin.json has "PDF_SPEC_DIR": "${PDF_SPEC_DIR}".

Host	${PDF_SPEC_DIR}	Where to write it
Claude Code	Expanded from settings.json or the shell	The env of Claude's MCP / plugin config
Grok Build 1.0.30	Not expanded in plugin env. Passing the literal fails startup (measured: REGISTRY_ERROR)	[mcp_servers.pdf-spec] in ~/.grok/config.toml

Grok Build does expand ${VAR} of the same key in config.toml. Plugin env and a direct config.toml entry are treated differently. After writing an absolute path in config.toml, grok inspect reported the source as config and list_specs returned 17 documents.

[mcp_servers.pdf-spec]
command = "npx"
args = ["-y", "@shuji-bonji/pdf-spec-mcp@latest"]
env = { PDF_SPEC_DIR = "/absolute/path/to/pdf-specs" }

PDF_WRITER_FONT has the same gap. A value in Claude Code's settings.json does not reach the pdf-writer process Grok Build spawns. On Grok Build, put an absolute path in [mcp_servers.pdf-writer] env, or pass fontPath on every call. Japanese output without a font is FONT_REQUIRED.

Step 3 — pdf-verify (veraPDF and trust anchors)

Works out of the box (a built-in subset of ~15 PDF/A rules + 12 PDF/UA rules). For serious use, install veraPDF.

1. Install veraPDF
2. Put it on PATH, or point PDF_VERIFY_VERAPDF at the executable

{
  "mcpServers": {
    "pdf-verify": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-verify-mcp@latest"],
      "env": {
        "PDF_VERIFY_VERAPDF": "/usr/local/bin/verapdf",
        "PDF_VERIFY_TRUST_ANCHORS": "/path/to/trust-anchors"
      }
    }
  }
}

Setting PDF_VERIFY_TRUST_ANCHORS (a directory of PEM/DER certificates) enables evaluation of the signer's certificate chain. Without it, a "valid" signature means only that the cryptography checks out — not that the signer is who they claim (trust: not_evaluated).

Step 4 — pdf-writer (CJK fonts)

The standard font (Helvetica) is ASCII only. To output Japanese or other CJK text you need an embeddable single-face font (.ttf / .otf; variable fonts are not supported). The static build of Noto Sans JP is recommended.

{
  "mcpServers": {
    "pdf-writer": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-writer-mcp@latest"],
      "env": { "PDF_WRITER_FONT": "/path/to/NotoSansJP-Regular.otf" }
    }
  }
}

With PDF_WRITER_FONT set, the per-tool fontPath can be omitted. Always pass outputPath (absolute) for output — omitting it returns the whole PDF as base64 and floods the response.

Step 5 — Smoke test

Hit one tool per server.

Server	Example prompt
pdf-reader	"Show me this PDF's page count and metadata"
pdf-spec	"What does ISO 32000-2 require for an annotation's /Contents?"
pdf-verify	"Verify the integrity of this PDF"
pdf-writer	"Create a PDF saying 'Hello 日本語' at ~/tmp/test.pdf"

Step 6 — Adding the Skills

Adding pdf-trust (incoming audit), pdf-publish (delivery) and pdf-read (reading) as Skills gives you a fixed choreography for multi-MCP workflows.

• pdf-trust requires pdf-verify — v0.7.0+ for evaluate_policy at all, v0.29.0+ recommended (v0.21.0 changed the top level of verify_signatures / detect_pades_level JSON from an array to an object; v0.27.0–v0.28.0 changed how revocation and validation time are judged; v0.29.0 stopped cutting JSON at a character count)
• pdf-publish requires pdf-writer, and pdf-verify at the conformance gate level (v0.20.0+ recommended for the scope field)
• pdf-read requires pdf-reader (v0.15.1+ recommended; runs on v0.14.0+)

Environment variables

Variable	Server	Required	Purpose
PDF_SPEC_DIR	pdf-spec	Required	Directory of the specification PDF corpus
PDF_SPEC_CACHE_DIR	pdf-spec	Optional	On-disk index cache (v0.5.0+; default ${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp). PDF_SPEC_CACHE=off disables it
PDF_READER_CONCURRENCY	pdf-reader	Optional	Concurrent remote fetches in read_url. Default 4
PDF_READER_RENDER_TIMEOUT_MS	pdf-reader	Optional	Per-page budget for render_page. Default 20,000 ms
PDF_VERIFY_VERAPDF	pdf-verify	Optional	veraPDF executable path (falls back to PATH lookup → built-in rules)
PDF_VERIFY_TRUST_ANCHORS	pdf-verify	Optional	Directory of trust anchor certificates
PDF_WRITER_FONT	pdf-writer	Effectively required for CJK output	Default font (single-face .ttf/.otf)

The full list, with defaults, is the environment variable reference.