PDF Letter MCP

Renders a structured letter as a print ready PDF laid out to DIN 5008, so the address sits in the window of a German envelope, entirely offline with no external API.

Local MCP server (stdio) that turns structured letter data into a print ready PDF. One fixed layout, the everyday German letter, with the recipient address positioned per DIN 5008 so it sits exactly in the window of DL and C6/C5 window envelopes. No web service, no external API, everything runs offline on your machine.

- One layout, no variants: return address line, recipient, right aligned "place, date", bold subject block with references below it, salutation, body, closing, signature, enclosures
- Address field 45 mm high ending at 105 mm from the left, with return address line, remark zone (Einschreiben, Nicht nachsenden) and address zone
- Return address, remarks and recipient are balanced inside the address field, so the block sits evenly in the envelope window and further address lines still fit.addressLayout: "din"switches back to the fixed zone boundaries
- Page breaks keep closing, signature image, name and enclosures together, follow-up pages carry recipient, date and page number
- Subject 33 mm below the address field, place and date three lines above it
- Fold marks at 105 mm and 210 mm, punch mark at 148.5 mm
- DIN 5008 writing margin of 25 mm on the left, and the address field follows it, so address, subject and body share one edge. The field keeps its right edge at 105 mm and stays inside the 90 mm envelope window
- Closing, one blank line, printed name.signature.spaceMmreserves more room for signing by hand
- Signature as an image file: PNG with alpha channel keeps its transparency, the image is laid over the blank line above the printed name and never shifts the text. Optional crop, background removal and ink recolouring for scans
- Multilingual: de, en, fr, es, it, nl, pt, pl, tr, da, sv, cs with locale aware date formats and address rules per country
- Language aware hyphenation, bold/italic markup, bullet and numbered lists, automatic page breaks with continuation headers
- Page numbers and a layout debug mode that draws the DIN 5008 zones
- Embedded Unicode fonts (DejaVu), any installed system font or a .ttf path

claude mcp add pdf-letter -- node "/absolute/path/to/pdf-letter-mcp/dist/src/index.js"

Or in~/.claude.json/claude_desktop_config.json:

{ "mcpServers": { "pdf-letter": { "command": "node", "args": ["/absolute/path/to/pdf-letter-mcp/dist/src/index.js"], "env": { "PDF_LETTER_OUTPUT_DIR": "~/Documents/Briefe" } } } }

Sender addresses and signatures live in a file on the machine, never in the prompt. A letter names a profile, the server fills in address, return address line and signature image verbatim.

{ "defaultProfile": "erika", "profiles": { "erika": { "description": "Erika Musterfrau, privat", "sender": { "name": "Erika Musterfrau", "street": "Musterstraße 12", "postalCode": "12345", "city": "Musterstadt", "country": "DE" }, "place": "Musterstadt", "locale": "de", "signature": { "path": "/pfad/zur/unterschrift.png" } } } }

create_letterthen only needs"profile": "erika"plus the content. The profile owns the identity: a sender or signature passed in the call is replaced by the profile,place,localeandclosingare defaults that a letter may override.list_profilesshows what is available. Without a profile and without a sender the letter is refused instead of being invented.

The file belongs outside the repository,profiles.jsonis in.gitignore.

The MCP tools take content only: addresses, date, subject, references, text, signature, enclosures. There are no parameters for margins, spacing, font, image size or position, and unknown fields sent by a client are dropped. Typography is an installation setting (PDF_LETTER_FONT,PDF_LETTER_FONT_SIZE), so every letter of one installation looks identical. The building blocks for a company letterhead, an information block and a footer are still in the library, but they are not reachable through the MCP.

The sender appears only in the small return address line above the recipient. Place and date sit right aligned above the bold subject block, references go directly below the subject.

{ "locale": "de", "sender": { "name": "Erika Musterfrau", "street": "Musterstraße 12", "postalCode": "12345", "city": "Musterstadt", "country": "DE" }, "recipient": { "company": "Stadtwerke Musterstadt", "street": "Industriestraße 8", "postalCode": "12345", "city": "Musterstadt" }, "place": "Musterstadt", "date": "2026-07-24", "dateStyle": "long", "subject": "Widerspruch gegen die Jahresabrechnung vom 01.07.2026", "subjectLines": ["Zeichen: SW-2026-0815", "Kunden-Nummer: 000000000"], "body": "hiermit widerspreche ich der Jahresabrechnung.\n\n- korrigierte Abrechnung\n- Eingangsbestätigung", "signature": { "path": "/pfad/zur/unterschrift.png", "widthMm": 45, "removeBackground": true, "trim": true, "name": "Erika Musterfrau" }, "enclosures": ["Kopie der Abrechnung"] }

Everything exceptsender,recipientandbodyis optional. The salutation is derived from the recipient (FrauplusDr. Erika MustermannbecomesSehr geehrte Frau Dr. Mustermann,), the date defaults to today, the closing to the locale default.

- Blank line: new paragraph
- Single newline: line break (setbodyModetomarkdownto reflow instead)
- - itemor1. item: bullet or numbered list
- bold,italic
- \pagebreakon its own line: forced page break

Two ways, both end up as a real image in the PDF:
- Pass the file directly:signature.pathplustrimandremoveBackground. The scan is cleaned on every render.
- Clean it once withprepare_signatureand reuse the resulting PNG. Faster and lets you check the result before it goes into a letter.

trim,removeBackgroundandinkColorneed the optionalsharpdependency, which is installed by default. A PNG that already has a transparent background works without it.

The image is an overlay: closing, one blank line, printed name stay exactly where they are, and the signature sits on top of that blank line and across the closing, the way a signature is written over "Mit freundlichen Grüßen" on paper. That overlap is the intended result.

Size and position are decided by the renderer, not by the caller. The signature is scaled to roughly the width of the closing line, around 50 mm, capped proportionally at 1.2 times that width and 28 mm in height. There is no parameter for width, height, offset or spacing, so nothing can shift the layout letter by letter.

npm test # geometry, address rules, typography, rendering npm run examples # writes sample letters to examples/

examples/holds the German letter, the same letter in English and a debug variant that draws the DIN 5008 zones, so the address field position can be checked against a window envelope.preview_letterreports the same measurements as JSON, plus warnings when the address is too long or does not fit the address field.

MIT, seeLICENSE. The bundled DejaVu fonts are covered by the Bitstream Vera and Arev licenses.

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar