# HTML to PDF in Cursor

Turn HTML files, templates or URLs into PDFs from Cursor's agent with the html-pdf.com remote MCP server. Paste one JSON config and you're done.

**Quick answer:** add `"html-pdf": { "url": "https://html-pdf.com/mcp", "headers": { "Authorization": "Bearer hp_live_..." } }` under `mcpServers` in `~/.cursor/mcp.json`, then ask the agent "Convert https://example.com to PDF".

## One-click install

This is the fastest way to connect. **[Add html-pdf to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=html-pdf&config=eyJ1cmwiOiJodHRwczovL2h0bWwtcGRmLmNvbS9tY3AifQ==)** opens Cursor with the server filled in.

Cursor then asks you to log in to html-pdf.com (OAuth), so you don't need to copy a key. New accounts get 100 free credits. Prefer a key in a config file? Follow the steps below instead.

## Get an API key

For the manual config you need a key. Get one at https://html-pdf.com/login, or with a single request:

```bash
curl -X POST https://html-pdf.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

Copy the `api_key` (shown once), then open the link we email you to confirm your address. That adds 100 free credits, and 1 credit = 1 PDF page.

## Connect

This step adds the server to Cursor. Put it in `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for a single project:

```json
{
  "mcpServers": {
    "html-pdf": {
      "url": "https://html-pdf.com/mcp",
      "headers": { "Authorization": "Bearer hp_live_..." }
    }
  }
}
```

It is a remote Streamable HTTP server, so there is nothing to install. Open **Cursor Settings → MCP** and check that `html-pdf` shows a green status and lists `html_to_pdf`, `url_to_pdf`, `get_credits`, `buy_credits`.

If you put the config in the project, keep the key out of git.

## Try it

Once connected, you just ask in plain words. You don't write any code. For example:

- "Render `templates/invoice.html` with the sample data in `fixtures/order.json` to a PDF."
- "Convert https://example.com/docs to PDF, A4, with screen styles."
- "Check how my receipt template paginates. Make a PDF and tell me how many pages it has."

You get back a download link (valid 24h), the page count and remaining credits.

## Tips

These habits help you iterate on templates without wasting credits.

- **Page breaks:** use `break-before: page` between sections and `break-inside: avoid` on rows and cards that must not split.
- **Page numbers:** `footer_html` with `<span class="pageNumber"></span> / <span class="totalPages"></span>`, plus a bottom `margin`.
- **Iterate on templates:** ask the agent to render, check the page count and adjust the CSS. Set `max_pages` so a broken loop never produces a 500-page PDF. Failed renders are free.
- **Production code:** ask the agent to call `POST https://html-pdf.com/v1/pdf` from your backend with the same options.

## Troubleshooting

Most issues come from invalid JSON or assets the renderer can't reach.

- **Red status in MCP settings:** the JSON is invalid, or the `Authorization` value is missing the `Bearer ` prefix.
- **403 `email_not_confirmed`:** the email behind the key isn't confirmed yet. Click the link we emailed you (it adds the 100 free credits), then try again.
- **Images missing in the PDF:** local paths like `./logo.png` can't be reached. Use absolute `https://` URLs or `data:` URIs.
- **Fonts look wrong:** load web fonts with an absolute URL (for example Google Fonts) in the HTML `<head>`.

## FAQ

### How do I add an MCP server in Cursor?

Add an entry under `mcpServers` in `~/.cursor/mcp.json` (or `.cursor/mcp.json` per project) with the server `url` and an `Authorization` header. Then check for a green status in **Cursor Settings → MCP**.

### Why are images missing from my PDF?

The renderer can't read local files like `./logo.png`. Use absolute `https://` URLs or `data:` URIs instead.

### Is it free to try?

Yes. Each new account gets 100 free credits once you confirm your email, with no card. 1 credit = 1 PDF page, and failed renders cost nothing.

### Do credits expire?

No. Purchased credits never expire. Packs go from $10 for 1,000 credits to $250 for 50,000.

Full reference: [API docs](https://html-pdf.com/docs) · [MCP server](https://html-pdf.com/mcp)