Mac-letterhead

Turn any Markdown file into a professionally-branded PDF on your company's letterhead — with no manual formatting. Mac-letterhead treats your letterhead PDF as digital stationery: it prints your Markdown into the safe area of the page (never overlapping your header, footer, or logo) and applies your brand's typography from a small CSS file.

Runs entirely on your Mac. Same engine as a drag-and-drop droplet, a command-line tool, or a Model Context Protocol server that Claude and other AI clients can call directly.

• What it does
• Install
• Quick start (2 minutes)
• Use it — droplet · CLI · MCP server
• Configure & fine-tune — brand CSS · blend strategies · multi-page
• Advanced · Privacy · License

What it does

You have a company letterhead — a PDF with your logo at the top, contact info at the bottom, maybe a subtle watermark. You have documents to write, and they need to be on that letterhead: proposals, reports, invoices, memos.

The traditional options are all painful: Word templates that never quite line up, copy-paste-adjust cycles into a designer's InDesign file, or manually placing text over the letterhead in a PDF editor. Or just giving up and sending unbranded.

Mac-letterhead does the whole thing automatically. It analyzes your letterhead PDF to find the safe printable area (the space around the header, footer, and logo), renders your Markdown into that area with your brand's typography (fonts and colors from a tiny CSS file), and hands you a finished PDF. Multi-page letterhead? First-page vs subsequent pages? Handled.

The same tool ships as three interfaces — a Mac drag-and-drop app (for you), a command-line utility (for scripting), and an MCP server (so Claude and other AI clients can produce your branded documents on request).

Install

Pick one:

Homebrew (recommended for everyday Mac use):

brew tap easytocloud/tap
brew install mac-letterhead

uvx (no permanent install; uses uv's ephemeral env):

uvx mac-letterhead --help

Claude Desktop (double-click install): Download the latest mac-letterhead-<version>.mcpb from the releases page and double-click it — Claude for macOS handles the rest.

System dependencies (optional but recommended)

For the best rendering quality (full CSS support via WeasyPrint), install the WeasyPrint system libraries once:

brew install pango cairo fontconfig freetype harfbuzz

Without them, Mac-letterhead falls back to ReportLab automatically — simpler output, no external deps, everything still works.

Quick start (2 minutes)

1. Put your letterhead somewhere Mac-letterhead can find it. The default convention is ~/.letterhead/<name>.pdf:

   bash

   Copy

   mkdir -p ~/.letterhead
   cp /path/to/your-letterhead.pdf ~/.letterhead/company.pdf
   

2. (Optional, but strongly recommended) Add typography. Create ~/.letterhead/company.css with your brand's fonts and colors:

   css

   Copy

   body        { font-family: "Inter", "Helvetica Neue", sans-serif; color: #1f2937; }
   h1, h2, h3  { color: #0b3d91; font-family: "Merriweather", Georgia, serif; }
   h1          { border-bottom: 2px solid #0b3d91; padding-bottom: 0.25em; }
   a           { color: #0b3d91; }
   

   Skip this and Mac-letterhead uses a clean default.

3. Create the droplet on your Desktop:

   bash

   Copy

   mac-letterhead install --name "company"
   

   A company.app appears on your Desktop.

4. Drop any .md or .pdf file onto the droplet. Choose where to save. You get a letterheaded PDF.

That's it. Every subsequent document is one drop.

Use it

Same engine, three interfaces.

🖱️ Drag-and-drop droplet

Best for human workflows on a Mac. One-time setup, then every future document is a drag onto a Desktop icon.

mac-letterhead install --name "company"        # uses ~/.letterhead/company.{pdf,css}
mac-letterhead install --name "personal"       # a second droplet for personal docs
mac-letterhead install --name "client-acme"    # one droplet per client / brand

Each droplet is a full macOS .app bundle you can drag around, put in the Dock, or Automator-chain. Dropping a file on it opens a save dialog for the output location.

Double-click the droplet (without dropping anything) to see the safe-area preview for that droplet's letterhead — cut marks, colour-coded tint, source label, all in one PDF that opens in your default viewer. Handy for verifying "will Markdown land where I expect it" before committing to a merge.

⌨️ Command line

Best for scripting, CI, or one-shot conversions. No droplet needed.

# Markdown → letterheaded PDF
mac-letterhead merge-md ~/.letterhead/company.pdf "Q3 Report" ~/Desktop report.md

# Existing PDF → letterheaded PDF
mac-letterhead merge ~/.letterhead/company.pdf "Contract" ~/Desktop contract.pdf

# Preview the safe area (cut marks + tint) as a PDF
mac-letterhead preview ~/.letterhead/company.pdf

Full reference: mac-letterhead --help.

🤖 MCP server for AI clients

Best when you want Claude, Claude Code, Cursor, Windsurf, or another AI assistant to produce branded documents on demand.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "letterhead": {
      "command": "uvx",
      "args": ["mac-letterhead[mcp]", "mcp"]
    }
  }
}

Then in Claude: "Draft a Q3 investor update on our company letterhead." Mac-letterhead handles the formatting; the PDF lands in ~/Desktop.

Published on the official MCP Registry as io.github.easytocloud/mac-letterhead — visible on Glama and PulseMCP. For full MCP configuration (style-specific servers, multiple brands from one client), see README_MCP.md.

Configure & fine-tune

Preview and mark the safe area

Mac-letterhead needs to know where on your letterhead is safe to print content — the space between the header, footer, and any logos. It figures this out in three tiers:

1. You mark it explicitly. Open your letterhead in Preview.app (Tools → Show Markup Toolbar → Rectangle), draw a box over the intended safe area, save. That's it — Preview.app doesn't offer any way to label annotations, so Mac-letterhead treats a single Square annotation on a page as the safe area even without a label. If you want to be unambiguous (or you're using a PDF editor that supports labeling), click your rectangle → sidebar → Description → type safe-area (or printable-area — case-insensitive, substring match). Then multiple rectangles per page work too — only the labeled one is used.
2. Auto-detected. No annotation → Mac-letterhead analyses the letterhead's layout (text, drawings, logos) and derives a safe rectangle that avoids them, with a ~40 pt safety pad.
3. Fallback default. No content detected → 1-inch margins on every side.

Preview the resolution any time:

mac-letterhead preview ~/.letterhead/company.pdf
# writes ~/.letterhead/company-preview.pdf

Colour code in the preview PDF — glance to see how confident the tool is:

Cut marks at each corner give print-native precision; a very subtle tint fills the region for gestalt. A tiny label at the bottom-left tells you which source drove the result and the safe area's exact dimensions.

Per-document options via YAML front matter