@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

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

3. 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_account
2. exactpdf_pdf_info(path="/absolute/path/document.pdf")
3. exactpdf_voice_preview(text="Short sample...", voice_style="professional")
4. 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_account | GET /api/v1/account | 0 | | exactpdf_pdf_info | POST /api/v1/pdf-info | 0 | | exactpdf_merge_pdfs | POST /api/v1/merge | 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_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