# MCP server

> Give Claude Code, Claude Desktop or any MCP client five Quire tools to render, validate and preview PDFs, with setup, tool reference and example prompts.

`quirepdf-mcp` is a Model Context Protocol server that lets an AI agent turn JSON into PDF files on your machine. It runs locally over stdio and calls the Quire API with your key.

## Add it to Claude Code

```bash
claude mcp add quire --env QUIRE_API_KEY=qk_live_... -- npx -y quirepdf-mcp
```

Files are saved to the directory Claude Code is running in. Run `/mcp` inside Claude Code to check that `quire` is connected.

## Add it to Claude Desktop

Open **Settings → Developer → Edit Config**, or edit the file directly:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quirepdf-mcp"],
      "env": {
        "QUIRE_API_KEY": "qk_live_...",
        "QUIRE_OUTPUT_DIR": "/Users/you/Documents/Quire"
      }
    }
  }
}
```

Restart Claude Desktop after saving. Set `QUIRE_OUTPUT_DIR` to an absolute path you can find; the server creates the folder if needed. Cursor and other MCP clients use the same `mcpServers` block.

You need Node.js 18 or later for `npx`. Get a key with `npx quirepdf-cli login you@example.com`.

## Environment variables

| Variable | Required | Meaning |
|---|---|---|
| `QUIRE_API_KEY` | yes | Your API key |
| `QUIRE_OUTPUT_DIR` | no | Where rendered files are saved. Default: the server's working directory. |
| `QUIRE_API_URL` | no | API base URL. Default `https://api.quirepdf.dev`. |

## Tools

| Tool | Input | What it does |
|---|---|---|
| `render_document` | `data` (object), `template?`, `format?` (`pdf` or `png`), `page?`, `output_path?`, `test?` | Renders and saves the file. With `test: true` the render is free and watermarked (handy while an agent iterates). Returns the path, template, how it was chosen, page count and size. For PNG it also returns the image, so the agent can look at the page. |
| `validate_document` | `data`, `template?` | Checks data without rendering and reports which template it resolves to. Free. |
| `list_templates` | none | The seven built-in layouts with a description of each |
| `get_template` | `name` | A template's JSON Schema and a complete sample, so the agent learns the fields |
| `get_usage` | none | Plan and renders used this month |

The server also tells the agent how Quire works: no template is needed, `title`/`from`/`to` shape the generic header, and `currency` turns on money formatting.

### Where files go

Without `output_path`, `render_document` saves `<template>-<timestamp>.pdf` (or `-p<page>.png`) in `QUIRE_OUTPUT_DIR`. A relative `output_path` is resolved against `QUIRE_OUTPUT_DIR`; an absolute one is used as is. If the path has no extension, `.pdf` or `.png` is added.

A typical result:

```json
{
  "saved_to": "/Users/you/Documents/Quire/invoice-2026-10-03T11-55-01.pdf",
  "template": "invoice",
  "template_source": "explicit",
  "pages": 1,
  "size_kb": 27,
  "render_ms": 6.1,
  "quota_remaining": 96
}
```

### Errors

Failures come back as tool errors the agent can read and act on:

```text
invalid_data: data has 2 problems
- seller is required
- items[0].qty must be a number
Tip: call get_template to see the expected fields, or omit `template` to use the generic layout.
```

Missing keys and exhausted quotas get a similar one-line explanation of what to do.

## Example prompts

- "Make me a PDF invoice for 3 hours of consulting at $150 an hour for Acme Corp. I'm Northwind Studio, 221 Market Street, San Francisco."
- "Turn `results.json` into a report PDF with the title 'Load test, October'."
- "Render a certificate of completion for Maya Chen for the Advanced TypeScript course, signed by me as course lead."
- "Preview page 2 of that invoice as an image and check that the totals look right."
- "How many renders do I have left this month?"

For a named document type, the agent usually calls `get_template` first, fills in the fields, then calls `render_document` with that template. For anything else it renders your data with the generic layout. The [MCP guide](/guides/ai-agents-generate-pdf-mcp) walks through a full conversation.

## Privacy

The server sends only the `data` the agent passes to a tool. Quire renders it in memory and doesn't store documents; see [Accounts and billing](/docs/accounts-and-billing#what-quire-stores).