MintPDF

---

Send HTML or Markdown, get a PDF back. It is Chromium under the hood, with the print CSS already worked out so tables don't split across pages, table headers repeat, and Markdown comes out looking like a document rather than a text file.

• Pagination is the point. break-inside, repeating thead, orphans and widows, and headers and footers that actually inherit your styling. See How it works.
• MCP native — generate_pdf and pdf_from_url over streamable HTTP, so an agent can produce a document mid-conversation.
• Documents aren't kept — rendered files are deleted after an hour, and their contents are never logged. Keys, emails and usage counters obviously are stored. See Security.
• Run it yourself — MIT, with a published image. The hosted service exists so you don't have to operate Chromium, not because the renderer is secret.

Quickstart

No signup, no key:

curl -X POST https://mintpdf.dev/v1/pdf \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Invoice #42\n\n| Item | Price |\n|---|---|\n| Widget | $9.00 |","pageNumbers":true}' \
  --output invoice.pdf

Want more than 10 renders a day? A free key (email only, no card) raises it to 100 a month:

curl -X POST https://mintpdf.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
# → {"key":"pm_…","daily_limit":100}   # 100 renders per month

Then send Authorization: Bearer pm_… with your requests.

Use it from Claude (or any MCP client)

{
  "mcpServers": {
    "mintpdf": {
      "command": "npx",
      "args": ["-y", "mintpdf-mcp"]
    }
  }
}

Prefer the hosted endpoint directly? Use mcp-remote instead:

{
  "mcpServers": {
    "mintpdf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mintpdf.dev/mcp"]
    }
  }
}

Restart your client, then just ask:

"Summarise this thread as a one-page brief with page numbers and give me a PDF."

Tool	Input	Returns
generate_pdf	html or markdown, plus options	download URL, valid 1 hour
pdf_from_url	url (public http/https), plus options	download URL, valid 1 hour

API

POST /v1/pdf

Body takes exactly one source, plus options:

Field	Type	Notes
html	string	Full document or fragment
markdown	string	Rendered with the default stylesheet
url	string	Public page to render. Private/internal addresses are blocked
format	string	A4 (default), Letter, Legal, A3, A5
landscape	boolean	default false
margin	string	all sides, e.g. "18mm"
headerText / footerText	string	small text on every page
pageNumbers	boolean	adds 3 / 7 to the footer
output	"pdf" | "url"	default returns PDF bytes; "url" returns JSON with a link

POST /v1/keys

{"email":"you@example.com"} → a free key. No card, no verification loop.

POST /mcp

MCP streamable-HTTP endpoint, stateless. Same capabilities as the REST API.

Postman

A ready-made collection covering every endpoint and option lives in postman/. Import it by link:

https://raw.githubusercontent.com/TrendTweekers/mintpdf/main/postman/mintpdf.postman_collection.json

The first request runs with no key at all, and fetching a free key stores it into the collection variable automatically, so the rest of the collection works straight after.

Limits

Tier	Limit	Price
Anonymous	10 renders/day per IP	free, no signup
Free key	100 renders/month	free, email only
Solo	3,000 renders/month	$19/month
Team	12,000 renders/month	$49/month
Scale	50,000 renders/month	$129/month

Self-host

MintPDF is MIT-licensed; run your own if you'd rather.

npm install
npm run build
npm start                # http://localhost:3000
node dist/smoke.js       # end-to-end render check

Or pull the published image, which has Chromium and the fonts baked in:

docker run -p 3000:3000 \
  -e BASE_URL=http://localhost:3000 \
  -e DATA_DIR=/data -v mintpdf-data:/data \
  ghcr.io/trendtweekers/mintpdf:latest

Then it is the same API on your own machine, with no limits and nothing leaving it:

curl -X POST http://localhost:3000/v1/pdf \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Local","pageNumbers":true}' --output local.pdf

Images are built and published by CI on every change, and each is smoke-tested by starting the container and rendering a real PDF from it before being tagged. Tags are latest and the short commit SHA. Building it yourself works too:

docker build -t mintpdf .
docker run -p 3000:3000 -e BASE_URL=http://localhost:3000 mintpdf

Environment: BASE_URL (used in download links), DATA_DIR (defaults to /tmp/mintpdf; mount a volume to persist keys), ANON_DAILY_LIMIT, FREE_MONTHLY_LIMIT, SOLO_MONTHLY_LIMIT, TEAM_MONTHLY_LIMIT, SCALE_MONTHLY_LIMIT, OVERAGE_FACTOR, RENDER_CONCURRENCY, RENDER_QUEUE, RENDER_QUEUE_WAIT_MS.

Load and admission control

Every render is a Chromium tab, so memory bounds concurrency long before CPU or cost does. Unbounded, a traffic spike opens a tab per request until the OOM reaper kills the container and every request fails, including ones nearly finished. Measured here: 30 concurrent renders with no gate left 30 orphaned Chrome processes and an unusable machine.

RENDER_CONCURRENCY renders run at once, RENDER_QUEUE more may wait, and anything beyond that is refused immediately with 503 and a Retry-After rather than being allowed to pile up. Turning some callers away in under a second is strictly better than serving everyone a timeout.

Code defaults are conservative (3 and 20). Measured on one small Railway instance at 10 and 70:

Burst	Served	Refused	Median	Wall clock	Instance after
45	45	0	1.5s	2.3s	healthy
120	81	39	3.0s	4.0s	healthy
250	80	170	3.4s	4.4s	healthy, 0.24s homepage

Roughly 18 renders a second sustained, with the refused share answered in under 2.7s. Raise the numbers only against a measurement on your own instance size, never on hope.

If you want a fuller self-hosted PDF toolchain (Office formats, merging, splitting), Gotenberg is excellent and does more than this does.

Security

This service renders HTML and URLs supplied by anyone, so the interesting questions are about what that content can reach.

Submitted HTML executes JavaScript. It has to: Mermaid diagrams and KaTeX maths are rendered in the page. Treat the renderer as running untrusted code, which is why the network restrictions below matter more than they would for a static converter.

SSRF is blocked at two layers.

1. A submitted url is parsed, restricted to http/https, and resolved. If any resolved address is private, the request is refused with a 400 before a browser is involved.
2. Independently, every request Chromium makes is intercepted and the destination resolved again at request time, then blocked if private. This covers embedded images, stylesheets, fonts, redirects and fetch() from submitted JavaScript, not just the URL you asked for.

The second layer resolves rather than trusting the hostname, and caches only refusals, never approvals: caching "this host is public" would reopen the exact hole the check exists to close. Unresolvable names fail closed.

Being precise about what that does and does not achieve: a DNS-rebinding attempt can no longer wait out a cached approval, so it has to win a race between this lookup and Chromium's own, on every request. That is a much narrower target than a fixed window, but it is a narrowed race rather than a closed door. Eliminating it entirely means pinning the resolved address at the socket layer, which is not implemented.

Blocked: loopback, 0.0.0.0, RFC1918, CGNAT (100.64/10), link-local and cloud metadata (169.254.169.254); IPv6 loopback, unspecified, link-local, site-local, unique-local, multicast, NAT64 and Teredo; IPv4-mapped and IPv4-compatible forms in either spelling, so ::ffff:10.0.0.1 and ::ffff:a00:1 are the same address and both are refused; localhost/.local/.internal names; any public hostname that resolves to a private address; and every scheme except http, https, data and blob.

Addresses are judged from their bytes rather than by matching text, because the same address has many spellings and a text match catches one and misses the rest.

There is a test suite for exactly this, and it is meant to be run rather than trusted:

BASE=https://mintpdf.dev node scratchpad/ssrf_suite.mjs

It checks the bypasses above and that ordinary rendering still works, because a guard that also blocks web fonts is a different bug rather than a fix.

The IPv6 parser has its own table of adversarial literals, since an invalid string silently becoming a valid address is the failure that matters in this kind of code:

node scratchpad/ipv6_table_test.mjs

Download links use a crypto.randomUUID() identifier and are not authenticated: anyone with the link can fetch the file for the hour it exists. That is deliberate, so a link can be emailed or handed to a browser, but it means the link is the secret.

Logging. Request metadata is logged (method, path, status, duration). Request bodies are never logged, so the HTML and Markdown you send are not written anywhere except the temporary file. The analytics table stores event kind, path, referrer, country and a daily-salted hash of the IP. No document content, and no way to reconstruct a document from it.

Limitations

Worth knowing before you build on it.

• Files are deleted after one hour. There is no document library and no way to fetch a render again later. Generate, use, done. If you need permanence, save the bytes on your side.
• No Office formats, merging or splitting. This converts HTML, Markdown and web pages, and nothing else. Gotenberg is more mature and covers far more ground if you are self-hosting and need that.
• One instance. Keys and quotas live in SQLite on a mounted volume, so running several replicas against one volume will not work. Horizontal scaling needs a real database first.
• Renders are admission-controlled. Over capacity the API returns 503 with Retry-After rather than queueing without limit. See the table above for measured behaviour.
• Two days old at the time of writing, with no paying users yet.

How it works

TypeScript, Fastify, and Puppeteer driving one shared Chromium with a page per request. node:sqlite holds keys, quotas and events, so there are no native dependencies to build.

The parts that took the actual work are the unglamorous ones:

• Print CSS. break-inside: avoid on tables, rows, list items, code blocks, blockquotes and figures; thead { display: table-header-group } so headers repeat; orphans/widows; break-after: avoid on headings so none is stranded at the foot of a page.
• Header and footer templates, which are a separate document from your page: they ignore the page CSS and render at near-zero font size unless the styles are inlined, and they sit outside the content margins.
• Admission control, because one Chromium tab per concurrent request is how the container runs out of memory.
• Network isolation for a renderer that executes untrusted JavaScript. See Security.

Licence

MIT — see LICENSE.