Pdfporter

pdfporter

Files in, PDFs out — and PDFs reshaped. pdfporter is a client for the conv2pdf conversion service: it takes the path of a file on your computer, sends it for conversion, and writes the result back next to the original. Office documents, spreadsheets, presentations, images, e-books, PostScript and HTML files become PDFs; PDFs become Word documents or per-page images; and PDFs can be merged, split, page-extracted, rotated, numbered, watermarked, compressed, password-protected and unlocked.

Configuration

• CONV2PDF_API_KEY (required for calls) — created in the conv2pdf dashboard, Developer tab. It is sent on every request as Authorization: Bearer . Without a key the server still starts and lists its tools; any tool call fails with a message explaining how to set the key.
• CONV2PDF_API_URL (optional) — API base URL. Defaults to https://api.conv2pdf.com/v1.
• CONV2PDF_TIMEOUT_MS (optional) — per-request timeout in milliseconds. Defaults to 120000, because a conversion may legitimately take up to about a minute.

Tools

• convert_to_pdf — convert a file to PDF, chosen from its extension: Word, Excel, PowerPoint, OpenDocument, Apple Pages, RTF, TXT and CSV files go through office-to-pdf; PNG, JPG, WebP, GIF and TIFF images through image-to-pdf; HEIC/HEIF photos through heic-to-pdf; EPUB through epub-to-pdf; PS/EPS through ps-to-pdf; HTML through html-to-pdf. An unknown extension fails locally, with no request made.
• convert_url_to_pdf — render a public web page to PDF from its address. It always takes an output_path, because there is no input file to write next to.
• convert_heic_to_jpg — an iPhone HEIC or HEIF photo as a JPG.
• convert_pdf_to_word — a PDF with real text as an editable DOCX document. Pass password to open a protected PDF.
• convert_pdf_to_images — one PNG (default) or JPG per page, delivered in a ZIP file.
• merge_pdfs — combine 2 to 20 PDFs into one, in the order given in paths.
• extract_pdf_pages — copy the pages listed in ranges (such as 1-5,7,10-12) into a new PDF, in the order written.
• split_pdf — one PDF per page, in a ZIP file.
• rotate_pdf — turn every page by rotation: 90, 180 or 270 degrees.
• add_page_numbers — number the pages, as "3 / 12" (format: "full", the default) or "3" (format: "simple"), at position bottom-center (default), bottom-left or bottom-right.
• add_watermark — stamp a text of up to 50 characters on every page.
• compress_pdf — reduce the size, with quality low, medium (default) or high, keeping images at 72, 150 or 300 DPI.
• protect_pdf — set a new password (6 to 64 characters), with prevent_print and prevent_copy to forbid printing or copying.
• unlock_pdf — remove a password you know (pass it as password), or the printing and copying restrictions.
• get_quota — the plan, usage and limits of the API key, returned verbatim.

Most PDF-reading tools accept an optional password that opens a protected PDF; the result has no password.

How a conversion behaves

1. The input file is read locally and POSTed as multipart/form-data to /convert/ , the file in the file field plus the tool's fields as string fields.
2. On HTTP 429 or 503 the server waits for the delay the API gives (the Retry-After header, else the body's retry_after seconds) and retries, at most twice and only for delays of 30 seconds or less.
3. The convert response carries a job_id and a relative download_url; the result is downloaded from the API origin, written to disk, and the job is then deleted from the service on a best-effort basis.

Results are never overwritten. By default the output sits next to the input: a conversion swaps the extension (report.docx gives report.pdf), a PDF operation adds a suffix (report.pdf gives report-compressed.pdf for compress_pdf, report-images.zip for convert_pdf_to_images, and so on), and a merge writes merged.pdf next to the first input. When the target name is taken, (2), (3), ... is appended before the extension until a free name is found. With an explicit output_path, an existing file there is refused before anything is sent.

A successful conversion answers with a JSON summary: {"job_id": ..., "output_path": ..., "size_bytes": ...}, plus the quota object copied from the convert response when the service sends one. get_quota returns the service's response body verbatim.

Errors: a non-2xx reply fails with conv2pdf error: when the body carries an error code, else conv2pdf error: HTTP ; an unreachable API fails with conv2pdf unreachable.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/pdfporter convert_to_pdf '{"path":"report.docx"}'

npx @reneturcios/pdfporter convert_url_to_pdf '{"url":"https://example.com/article","output_path":"article.pdf"}' npx @reneturcios/pdfporter convert_heic_to_jpg '{"path":"IMG_0001.heic"}' npx @reneturcios/pdfporter convert_pdf_to_word '{"path":"report.pdf"}' npx @reneturcios/pdfporter convert_pdf_to_images '{"path":"report.pdf","format":"jpg"}' npx @reneturcios/pdfporter merge_pdfs '{"paths":["a.pdf","b.pdf"]}' npx @reneturcios/pdfporter extract_pdf_pages '{"path":"report.pdf","ranges":"1-5,7,10-12"}' npx @reneturcios/pdfporter split_pdf '{"path":"report.pdf"}' npx @reneturcios/pdfporter rotate_pdf '{"path":"scan.pdf","rotation":90}' npx @reneturcios/pdfporter add_page_numbers '{"path":"report.pdf","position":"bottom-right"}' npx @reneturcios/pdfporter add_watermark '{"path":"contract.pdf","text":"CONFIDENTIAL"}' npx @reneturcios/pdfporter compress_pdf '{"path":"big.pdf","quality":"low"}' npx @reneturcios/pdfporter protect_pdf '{"path":"confidential.pdf","password":"secret123","prevent_print":true}' npx @reneturcios/pdfporter unlock_pdf '{"path":"protected.pdf","password":"secret123"}' npx @reneturcios/pdfporter get_quota '{}' npx @reneturcios/pdfporter --version

Exit codes: 0 on success, 1 on a runtime error, 2 on a usage error.

MCP server

npx -y @reneturcios/pdfporter mcp

MCP client config:

{

"mcpServers": { "pdfporter": { "command": "npx", "args": ["-y", "@reneturcios/pdfporter", "mcp"], "env": { "CONV2PDF_API_KEY": " " } } } }

Docker

docker run -i ghcr.io/cloudcorprecords/pdfporter

docker run --rm ghcr.io/cloudcorprecords/pdfporter get_quota '{}'

Development

npm install

npm run build # tsc -> dist/ npm test # tsx --test test/*.test.ts (fake fetch only, no network) npm run dev # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios