@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, extract, narrate, translate, or export PDFs 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.

Setup

• Create an API key at exactpdf.com (Max → API keys).
• 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")

Document outputs are saved to EXACTPDF_API_OUTPUT_DIR or your OS temp directory. Paid document tools consume credits only on successful output. Async speech jobs are metered by generated minutes.

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_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_structured_markdown	POST /api/v1/pdf-structured-markdown	1
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	1/min
exactpdf_pdf_to_audiobook	POST /api/v1/pdf-to-audiobook	1/min
exactpdf_generate_audiobook	POST /api/v1/generate-audiobook	1/min
exactpdf_translate_and_speak	POST /api/v1/translate-and-speak	3/min
exactpdf_presentation_narration	POST /api/v1/presentation-narration	1/min
exactpdf_job_status	GET /api/v1/jobs/:id	0
exactpdf_get_speech_job	GET /api/v1/speech-jobs/:id	0
exactpdf_download_audio	GET /api/v1/speech-jobs/:id/download	0

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
Text / Markdown	Absolute local PDF path	JSON text/Markdown, page count, structured content
Voice preview	Short text, voice style/language	Saved MP3/WAV preview, no credit charge
Speech jobs	PDF path, page range, style, callback URL	job_id, status URL, pricing estimate
Job polling/download	job_id	progress/errors/result URL or saved audio/ZIP

Async audiobook flow:

1. exactpdf_estimate_speech_cost(path="/abs/book.pdf", mode="audiobook")
2. exactpdf_voice_preview(text="Read the first paragraph in an audiobook tone", voice_style="audiobook")
3. exactpdf_generate_audiobook(path="/abs/book.pdf", voice_style="audiobook")
4. exactpdf_get_speech_job(job_id="...", download=false)
5. exactpdf_download_audio(job_id="...") after status is succeeded

exactpdf_pdf_to_speech, exactpdf_pdf_to_audiobook, and exactpdf_generate_audiobook accept optional callback_url and webhook_secret. ExactPDF signs webhook bodies with x-exactpdf-signature: sha256=<hmac> over timestamp.body.

Multilingual speech flow:

1. exactpdf_translate_and_speak(path="/abs/training.pdf", target_language="hi")
2. exactpdf_job_status(job_id="...", download=false)
3. exactpdf_job_status(job_id="...", download=true) after status is succeeded

segmentation_mode="pages" is useful for presentation narration because each PDF page becomes a trackable audio section.

Presentation narration flow:

1. exactpdf_presentation_narration(path="/abs/deck.pdf")
2. exactpdf_job_status(job_id="...", download=true) after status is succeeded

The default ZIP includes one MP3 per PDF page plus manifest.json with page numbers and duration seconds.

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 before speech/audiobook/translation jobs.
• Use exactpdf_voice_preview before full narration when quality matters.
• Async jobs are not downloads. Submit, poll, then download after succeeded.
• 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/docs/api

License

MIT