PDFOven

npx add-mcp 'https://pdfoven.com/mcp'

API documentation

Base URL: https://pdfoven.com. All requests use JSON and an API key from your dashboard (free signup). The whole API is described in the OpenAPI 3.1 spec.

Quickstart

1. Create a free account; your API key is ready right away and set it as PDFOVEN_KEY.
2. Run this. It uses the built-in invoice template, so it works with no setup:

curl https://pdfoven.com/v1/pdf \
  -H "Authorization: Bearer $PDFOVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"tpl_invoice","data":{"number":"INV-0001"}}' \
  -o invoice.pdf

The response body is the PDF (Content-Type: application/pdf), with headers X-Render-Ms (render time) and X-Usage-Remaining (renders left this month). Errors come back as JSON, described under Errors.

Authentication

Send your key as a bearer token: Authorization: Bearer po_live_…. The X-API-Key header also works.

POST /v1/pdf

Renders a PDF. Provide exactly one source:

html	An HTML string. Fragments are wrapped in a document with sensible base styles.
markdown	A Markdown string (GitHub-flavored).
url	A public http(s) URL to capture.
template + data	An inline Handlebars template and the JSON to fill it with.
template_id + data	A template saved in your dashboard, or a built-in template such as tpl_invoice. If data is omitted, its sample data is used.

Optional fields:

css	Extra CSS appended to the document.
options.format	A4 (default), Letter, Legal, A3, A5, Tabloid
options.landscape	Boolean, default false.
options.margin	Uniform margin such as "0.5in", "12mm" or "20px".
options.print_background	Print background colors and images. Default true.
options.header_template / footer_template	HTML for a repeating header/footer. Use <span class="pageNumber"></span> and <span class="totalPages"></span>. Requires a margin so it has room.
options.scale	0.1 – 2.
wait_for_selector	Wait for a CSS selector before rendering, for pages that draw charts with JavaScript.
timeout_ms	1,000 – 60,000. Default 30,000.
response	"binary" (default) returns the file. "base64" returns JSON { "data": "…", "content_type": "application/pdf", "bytes": 1234 }.
filename	Sets the Content-Disposition filename.

curl https://pdfoven.com/v1/pdf \
  -H "Authorization: Bearer $PDFOVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello, PDF</h1>","options":{"format":"Letter","margin":"0.5in"}}' \
  --output hello.pdf

POST /v1/image

Takes the same sources as /v1/pdf and returns a PNG. Call /v1/image?type=jpeg for a JPEG instead. Image options in options: width, height, full_page, device_scale_factor (1–3) and quality (JPEG only). Useful for social share images and certificates.

curl "https://pdfoven.com/v1/image" \
  -H "Authorization: Bearer $PDFOVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"<div style=\"padding:60px;font:700 64px sans-serif\">{{title}}</div>","data":{"title":"Launch day"},"options":{"width":1200,"height":630}}' \
  --output og.png

Templates

Templates are HTML with Handlebars placeholders, plus optional CSS and default page options. Create them in the dashboard with a live preview, or via the API. Markdown templates are also supported.

Built-in templates

Every account can render these without saving anything; they don't count toward your template limit. Send any subset of fields in data and the rest come from the sample data, so {"template_id":"tpl_invoice","data":{"number":"INV-2041"}} works as-is with a new key.

tpl_invoice	Clean invoice with line items, tax and totals.
tpl_receipt	Compact payment receipt for e-commerce and SaaS.
tpl_certificate	Landscape certificate of completion.
tpl_report	Readable multi-page report written in Markdown.
tpl_paystub	Earnings statement with hours, rates, deductions and net pay.
tpl_packing_slip	Order packing slip with ship-to address, SKUs and quantities, no prices.

To customize one, open it in the template editor as a starter and save your own copy.

Built-in helpers:

{{formatCurrency amount "EUR"}}	Formats money. Defaults to USD.
{{formatNumber value 2}}	Fixed decimals.
{{formatDate issued_at "medium"}}	short / medium / long / full.
{{sum items "amount"}}	Sums a field across an array.
{{lineTotal items "qty" "price"}}	Sum of qty × price across an array.
{{multiply a b}}, {{add a b}}	Arithmetic.
{{#if (eq status "paid")}}	Equality checks.
{{upper text}}	Uppercase.

GET /v1/templates

Lists your templates.

POST /v1/templates

{
  "name": "Invoice",
  "engine": "handlebars",
  "content": "<h1>Invoice {{number}}</h1>",
  "css": "h1 { color: #c8155f }",
  "sample_data": { "number": "INV-1" },
  "page_options": { "format": "Letter", "margin": "0.5in" }
}

GET /v1/usage

Returns your plan, limit and renders used this calendar month (UTC).

{ "plan": "starter", "period": "2026-10", "used": 412, "limit": 2000 }

Errors

Errors are JSON: { "error": { "code": "quota_exceeded", "message": "…" } }

400	invalid_request — the body failed validation.
401	unauthorized — missing or invalid API key.
404	template_not_found
422	template_error or render_failed (blocked URL, timeout, HTTP error).
429	quota_exceeded — monthly limit reached. Failed renders don't count.

MCP server for AI agents

PDFOven speaks the Model Context Protocol over Streamable HTTP at https://pdfoven.com/mcp. Agents get render_pdf and render_image, plus list_templates, get_template, create_template, update_template and delete_template to manage saved templates. Rendered files come back as embedded resources.

Claude Code:

claude mcp add --transport http pdfoven https://pdfoven.com/mcp \
  --header "Authorization: Bearer $PDFOVEN_KEY"

Cursor / other clients (mcp.json):

{
  "mcpServers": {
    "pdfoven": {
      "url": "https://pdfoven.com/mcp",
      "headers": { "Authorization": "Bearer po_live_..." }
    }
  }
}

Limits

• HTML up to 5 MB per request; render timeout up to 60 seconds.
• URL rendering is limited to public addresses.
• Rendered files are not stored.

Support

Questions or a render that looks wrong? Email support@pdfoven.com with the request you sent and the error code you got back.