@exactpdf/mcp

@exactpdf/mcp

Model Context Protocol (stdio) server for ExactPDF — production PDF tools for Cursor, Claude Desktop, Codex, and any MCP client.

Use it when an agent needs to inspect, merge, split, rotate, compress to upload limits, extract text, export PDF JSON, export structured Markdown for RAG, or build images-to-PDF workflows without writing fragile PDF plumbing.

Design principle: every tool should work on first run, explain credit cost before risky work, return a local output path for files, and expose precise HTTP/API errors when something fails.

Developer quickstart: https://exactpdf.com/developers

Setup

• Create an API key at max.exactpdf.com/account. New accounts get 20 free test credits. Buy one-time credit packs only after the workflow works; no subscription is required for API/MCP.
• Export:

export EXACTPDF_API_KEY="sk_live_…"
# Optional: default https://exactpdf.com
export EXACTPDF_API_BASE="https://exactpdf.com"
# Optional: where API binary outputs are written (default: OS temp dir)
export EXACTPDF_API_OUTPUT_DIR="/tmp"
# Backward-compatible alias:
export EXACTPDF_MERGE_OUTPUT_DIR="/tmp"

• Add to your MCP config (Cursor → Settings → MCP):

{
  "mcpServers": {
    "exactpdf": {
      "command": "npx",
      "args": ["-y", "@exactpdf/mcp"],
      "env": {
        "EXACTPDF_API_KEY": "sk_live_…"
      }
    }
  }
}

For a local checkout of this monorepo:

"command": "node",
"args": ["/path/to/ExactPDF/packages/exactpdf-mcp/dist/run.js"]

Tools

Safe first run:

1. exactpdf_first_run_checklist
2. exactpdf_account
3. exactpdf_pdf_info(path="/absolute/path/document.pdf")
4. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
5. exactpdf_estimate_speech_cost(path="/absolute/path/document.pdf", mode="audiobook") # planning only while background audio is hardened

Document outputs are saved to EXACTPDF_API_OUTPUT_DIR or your OS temp directory. Paid document tools consume credits only on successful output.

Background PDF speech, audiobook, translate-and-speak, and presentation narration submissions are currently disabled for paid workloads while ExactPDF finishes dedicated worker hardening and queue-completion smoke. exactpdf_voice_preview remains available for short free samples, and exactpdf_estimate_speech_cost is planning-only until the API is re-enabled.

Credit model:

• Free probes: checklist, account, PDF info, voice preview, speech cost estimate, and job polling.
• New accounts: 20 free test credits for API/MCP workflows.
• Standard document tools: 1 credit only after a successful output.
• Background audio jobs: planning-only until dedicated worker smoke passes.
• One-time packs: available in Max Account when you need more; no subscription required for API/MCP.

Tool	Endpoint	Credits
exactpdf_first_run_checklist	local guidance	0
exactpdf_account	GET /api/v1/account	0
exactpdf_pdf_info	POST /api/v1/pdf-info	0
exactpdf_merge_pdfs	POST /api/v1/merge	1
exactpdf_merge_and_compress_pdfs	POST /api/v1/merge-compress	1
exactpdf_split_pdf	POST /api/v1/split	1
exactpdf_rotate_pdf	POST /api/v1/rotate	1
exactpdf_compress_pdf	POST /api/v1/compress	1
exactpdf_compress_pdf_to_target	POST /api/v1/compress + target_bytes	1
exactpdf_compress_pdf_to_100kb	POST /api/v1/compress + 102400 target_bytes	1
exactpdf_compress_pdf_to_200kb	POST /api/v1/compress + 204800 target_bytes	1
exactpdf_compress_pdf_to_500kb	POST /api/v1/compress + 512000 target_bytes	1
exactpdf_compress_pdf_to_1mb	POST /api/v1/compress + 1048576 target_bytes	1
exactpdf_pdf_to_images	planned /api/v1/pdf-to-images	backend required
exactpdf_images_to_pdf	POST /api/v1/images-to-pdf	1
exactpdf_images_to_pdf_and_compress	POST /api/v1/images-to-pdf-compress	1
exactpdf_extract_text	POST /api/v1/extract-text	1
exactpdf_pdf_to_json	POST /api/v1/pdf-to-json	1
exactpdf_pdf_structured_markdown	POST /api/v1/pdf-structured-markdown	1
exactpdf_ocr_pdf	planned /api/v1/ocr	backend required
exactpdf_estimate_speech_cost	local estimate	0
exactpdf_voice_preview	POST /api/v1/voice-preview	0
exactpdf_pdf_to_speech	POST /api/v1/pdf-to-speech	disabled / hardening
exactpdf_pdf_to_audiobook	POST /api/v1/pdf-to-audiobook	disabled / hardening
exactpdf_generate_audiobook	POST /api/v1/generate-audiobook	disabled / hardening
exactpdf_translate_and_speak	POST /api/v1/translate-and-speak	disabled / hardening
exactpdf_presentation_narration	POST /api/v1/presentation-narration	disabled / hardening
exactpdf_job_status	GET /api/v1/jobs/:id	0 / legacy polling
exactpdf_get_speech_job	GET /api/v1/speech-jobs/:id	0 / legacy polling
exactpdf_download_audio	GET /api/v1/speech-jobs/:id/download	0 / legacy download

Tool behavior

Tool family	What the agent provides	What ExactPDF returns
Account / inspect	API key, local PDF path	JSON balance, page count, metadata
PDF operations	Absolute local PDF paths	Saved PDF/ZIP path plus remaining credits and measured size headers
Target-size compression	Absolute local PDF path, target bytes or preset	Saved PDF plus X-Target-Reached, original bytes, output bytes
Text / JSON / Markdown	Absolute local PDF path	JSON text/pages/metadata or Markdown, page count, structured content
Backend-required PDF images/OCR	Desired path/options	Clear backend-required message plus live browser tool URL
Voice preview	Short text, voice style/language	Saved MP3/WAV preview, no credit charge
Audio planning	Short text, character count, rough PDF size	Voice preview or estimated minutes/credits
Legacy job polling/download	job_id	progress/errors/result URL or saved audio/ZIP for jobs created before the hardening gate

Background audio status:

1. exactpdf_estimate_speech_cost(path="/abs/book.pdf", mode="audiobook") # planning only
2. exactpdf_voice_preview(text="Read the first paragraph in an audiobook tone", voice_style="audiobook")
3. Do not call exactpdf_generate_audiobook / exactpdf_pdf_to_speech for paid workloads until ExactPDF announces worker smoke has passed.

The disabled background audio tools intentionally return an MCP error message before submitting work. This protects users from paying for a path that is still being hardened.

Reliability rules for agent builders

• Always call exactpdf_account once before paid tools.
• Use absolute file paths. Relative paths are client-dependent and may fail.
• Use exactpdf_pdf_info before large jobs to confirm the file is readable.
• Use exactpdf_estimate_speech_cost for audio planning only until worker smoke passes.
• Use exactpdf_voice_preview before making any narration-quality decision.
• Do not promise PDF-to-MP3/audiobook output through MCP until background audio is re-enabled.
• If a tool returns isError, show the HTTP status and response body to the user. The API returns structured error details.
• Keep API keys out of prompts, logs, screenshots, and commits.

Publish checklist

npm run mcp:package:check
cd packages/exactpdf-mcp
npm publish --access public
npx -y mcp-publisher publish --file server.json

The package must exist on the public npm registry before the MCP Registry can verify mcpName.

Docs

• https://exactpdf.com/developers
• https://exactpdf.com/docs/api

License

MIT