# MCP server (Claude, Cursor and other AI assistants)

> This page as Markdown. Index of all PDFik docs: https://docs.pdfik.net/llms.txt — HTML version: https://docs.pdfik.net/integrations/mcp

The PDFik MCP server lets an AI assistant create PDFs, screenshots and Factur-X
e-invoices for you. You ask in plain words — "make a PDF of this page in A4 landscape" —
and the file lands in a folder on your computer.

- Package: [`@pdfik/mcp`](https://www.npmjs.com/package/@pdfik/mcp) — source: [github.com/pdfik/pdfik-mcp](https://github.com/pdfik/pdfik-mcp) (MIT)
- Runs locally over stdio; needs **Node.js 22 or newer**
- Works with any MCP client: Claude Desktop, Claude Code, Cursor, Cline, Windsurf and others

## Install

### Claude Code

```bash
claude mcp add pdfik --env PDFIK_API_KEY=sk_live_YOUR_API_KEY -- npx -y @pdfik/mcp@0.1.0
```

### Claude Desktop

Download `pdfik-mcp-0.1.0.mcpb` from the [releases page](https://github.com/pdfik/pdfik-mcp/releases)
and open it: Claude Desktop installs the server and asks for your API key. Or add it to
`claude_desktop_config.json` yourself, as below.

### Cursor and other clients

Add the server to the client's MCP configuration (`~/.cursor/mcp.json` for Cursor):

```json
{
  "mcpServers": {
    "pdfik": {
      "command": "npx",
      "args": ["-y", "@pdfik/mcp@0.1.0"],
      "env": {
        "PDFIK_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}
```

### Settings

| Variable | Required | Meaning |
| :-- | :-- | :-- |
| `PDFIK_API_KEY` | yes | Your API key from the [dashboard](https://pdfik.net/dashboard/api-keys) |
| `PDFIK_OUTPUT_DIR` | no | Folder for saved files (default `~/Downloads/PDFik`) |
| `PDFIK_TEST_MODE` | no | `1` makes every job a free [test job](https://docs.pdfik.net/testing) with sample output |

## Tools

| Tool | What it does |
| :-- | :-- |
| `url_to_pdf` | A public web page to PDF — paper format, margins, header and footer, watermark, compression, scale; optionally a Factur-X e-invoice |
| `html_to_pdf` | HTML markup (up to 512 KiB, [sanitized](https://docs.pdfik.net/html-to-pdf)) to PDF |
| `markdown_to_pdf` | Markdown (CommonMark + GFM tables) to PDF |
| `url_to_image` | A web page as PNG or JPEG |
| `html_to_image` | HTML markup as PNG or JPEG |
| `einvoice_to_pdf` | A [Factur-X / ZUGFeRD](https://docs.pdfik.net/einvoicing) PDF/A-3 from CII invoice XML |
| `get_job` | The status of a job |
| `download_job` | Saves the output of a finished job (up to 3 downloads, for 24 hours) |
| `get_account` | Your plan, quota window, usage and limits — creates nothing |

A tool waits for the render — up to about 45 seconds, as in [sync mode](https://docs.pdfik.net/url-to-pdf) —
and saves the file. The assistant gets the path and a link to the file; a small
screenshot also comes with a preview. For long renders the assistant can pass
`wait: false` and finish with `get_job` and `download_job`.

## How your data and key are handled

- The key is read from the environment only. It is never a tool argument and never part
  of a tool result, so it does not enter the conversation.
- Files are written only inside the output folder, under a cleaned-up name, and never
  overwrite an existing file.
- The tools have no option to send output to another address (no webhook, no delivery
  URL) and no option to pass page credentials, so text on a rendered page cannot make the
  assistant send your documents elsewhere.
- Each job uses one document of your quota, exactly as an API call does. Test mode is free.

## Troubleshooting

| Message | What to do |
| :-- | :-- |
| `PDFIK_API_KEY is not set` | Add the key to the server's `env` and restart the client |
| `[401] ...` | The key is wrong or revoked — create a new one |
| `[403] ... not whitelisted` | The key has an IP whitelist that does not include your address |
| `[503] Service Unavailable - Render Did Not Finish In Time ...` | The render took longer than 45 s; ask again with `wait: false` |
| `[429] ...` | A rate or quota limit; the message says which ([rate limits](https://docs.pdfik.net/rate-limits)) |

Every error names its code; the meanings are on [error codes](https://docs.pdfik.net/error-codes).
