@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

One-minute Setup

ExactPDF MCP is free to install. Hosted ExactPDF API workflows include 20 free test credits, then pay-as-you-go credits when the workflow is worth automating.

• 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"]

Copy-paste Configs

Use this bare config when your client lets you set environment variables separately:

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

Use this config when the client supports env values inside JSON:

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

Claude Desktop

Add to claude_desktop_config.json, then restart Claude Desktop:

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

Claude Code

Add the server from your project terminal:

claude mcp add exactpdf -- npx -y @exactpdf/mcp
export EXACTPDF_API_KEY="sk_live_..."

If your Claude Code setup stores env values in its MCP config, use the JSON block above instead.

Cursor

Add to .cursor/mcp.json or Cursor Settings -> MCP:

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

Windsurf

Add ExactPDF as a custom MCP server:

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

VS Code / Cline

Add to your Cline MCP settings:

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

Five Agent Recipes

Paste one of these after the MCP server is connected. Use absolute local file paths.

Merge these 3 PDFs into one file:
/Users/me/Desktop/cover.pdf
/Users/me/Desktop/form.pdf
/Users/me/Desktop/id.pdf

Compress /Users/me/Desktop/application.pdf under 500KB for a government upload.
Use ExactPDF MCP and save the output next to the original.

Convert /Users/me/Desktop/manual.pdf to structured Markdown for RAG.
Keep headings and page references.

Extract metadata and per-page JSON from /Users/me/Desktop/contract.pdf.
Show me the page count, title, author, and first-page text.

Turn these images into one PDF:
/Users/me/Desktop/photo-1.jpg
/Users/me/Desktop/photo-2.jpg
/Users/me/Desktop/photo-3.jpg

30-Second Demo

Video: https://exactpdf.com/demos/exactpdf-mcp-demo.mp4

Install ExactPDF MCP, paste one config block, ask your agent to fix a PDF, and get a local output file.

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")
6. exactpdf_generate_audiobook(path="/absolute/path/document.pdf", output_format="m4b")

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

English PDF speech, audiobook, and presentation narration use a dedicated queue and worker. Launch limits are 1 MB, 20 selected pages, 18,000 narrated characters, 20 generated minutes, and one active audio job per account. Translation remains disabled until multilingual pronunciation and provider-cost gates pass.

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.
• MP3/M4B narration: 15 credits per generated minute.
• MP4 presentation narration: 20 credits per generated minute.
• 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	15/min MP3/M4B; 20/min MP4
exactpdf_pdf_to_audiobook	POST /api/v1/pdf-to-audiobook	15/min MP3/M4B; 20/min MP4
exactpdf_generate_audiobook	POST /api/v1/generate-audiobook	15/min MP3/M4B; 20/min MP4
exactpdf_translate_and_speak	POST /api/v1/translate-and-speak	disabled / multilingual hardening
exactpdf_presentation_narration	POST /api/v1/presentation-narration	20/min MP4
exactpdf_job_status	GET /api/v1/jobs/:id	0 / polling
exactpdf_get_speech_job	GET /api/v1/speech-jobs/:id	0 / polling
exactpdf_download_audio	GET /api/v1/speech-jobs/:id/download	0 / 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
Audio generation	English PDF up to launch limits	Queued job, pricing, progress, and saved MP3/M4B/MP4

Bounded audio workflow:

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", output_format="m4b", language="en")
4. exactpdf_get_speech_job(job_id="...", download=true)

Audio submissions are rejected before queueing when they exceed launch limits. Translate-and-speak intentionally returns an error before paid work begins.

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 and obtain user approval before paid audio.
• Use exactpdf_voice_preview before making any narration-quality decision.
• Do not promise translated audio; translate-and-speak remains disabled.
• 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