# pdf-filler-mcp

An MCP server that lets Claude fill any PDF form — scanned or AcroForm — through a browser-based drag-and-drop editor.

**Editor** — drag, reposition and edit fields directly on the rendered PDF page:

![Drag-and-drop editor showing W-9 form with pre-filled fields and navigation bar](docs/screenshot-editor.png)

**Result** — the generated PDF with all fields overlaid:

![Filled W-9 form with name, address and SSN fields populated](docs/screenshot.png)

## How it works

1. **Claude renders** the PDF to images and inspects the layout
2. **Claude places markers** on each field and iterates until placement is correct
3. **Claude opens the editor** — a self-contained HTML page where you drag fields, edit values and click *Fertig*
4. **PDF is generated automatically** — the editor POSTs to a local receiver which runs headless Playwright to produce the final PDF

The entire stack runs locally. No data leaves your machine.

## Tools exposed

| Tool | Description |
|------|-------------|
| `pdf_render` | Render all pages to PNG at a given DPI, returns scale factor |
| `pdf_preview` | Overlay numbered coloured marker dots on a page for iterative placement verification |
| `pdf_editor_multi` | Generate a multi-page drag-and-drop HTML editor pre-filled with field values |
| `pdf_fill` | Directly overlay text on a PDF without opening the browser editor |
| `pdf_merge` | Merge per-page PDFs into a single file |
| `pdf_memory_get` | Retrieve saved field layout for a known form type |
| `pdf_memory_set` | Save verified field layout so the same form can be filled again instantly |
| `pdf_receiver_start` | Start the local HTTP receiver that auto-generates the PDF on *Fertig* |
| `pdf_receiver_wait` | Block until the user clicks *Fertig* and the PDF is ready |

## Prerequisites

- Python 3.9+
- [pymupdf](https://pymupdf.readthedocs.io/) (`pip install pymupdf`)
- [pypdf](https://pypdf.readthedocs.io/) (`pip install pypdf`) — for merging
- [Node.js](https://nodejs.org/) + [Playwright](https://playwright.dev/) — for the auto-PDF-generation step (`npm i -g playwright`)

## Installation

### 1. Clone

```bash
git clone https://github.com/patroqueeet/pdf-filler-mcp.git ~/.claude/pdf-filler
```

### 2. Register with Claude Code

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "pdf-filler": {
      "command": "python3",
      "args": ["~/.claude/pdf-filler/filler.py", "serve"]
    }
  }
}
```

Restart Claude Code — the `pdf_*` tools will be available in any session.

## Typical workflow

```
User: Fill out /tmp/application.pdf with my personal data

Claude:
  1. pdf_render       → get page images + scale_factor
  2. pdf_preview      → place marker dots, read result image, adjust
  3. pdf_memory_get   → check if layout is already saved
  4. pdf_receiver_start → start PDF receiver on port 7789
  5. pdf_editor_multi → open editor in browser
  6. pdf_receiver_wait → wait for user to click Fertig
  → returns: { done: true, output_path: "/tmp/application_filled.pdf" }
```

## Editor features

- **Click to create** a field anywhere on the document image
- **Drag** the ⣿ handle to reposition
- **Tab** between fields; inline editing
- **Checkbox** type available via the ➕ button
- Multi-page navigation with per-page field state
- Print CSS hides all editor chrome — only text overlays are printed

## Running the tests

```bash
pip install pymupdf pypdf pytest pytest-timeout
pytest tests/ -v
```

## License

MIT — see [LICENSE](LICENSE).