Mac-letterhead

PyPI Version Homebrew Python macOS Build License MCP Registry Downloads

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.

A plain report.md becomes a letterheaded PDF via Mac-letterhead

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:

    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:

    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:

    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, use Markup → Rectangle to draw a box over the intended safe area, click the shape → sidebar → Description → type safe-area (or printable-area — case-insensitive; substring match). Save. Mac-letterhead treats your rectangle as exact intent.
  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:

Colour Source What it means
Green annotation You marked it. Trusted verbatim.
Slate blue auto-detected Heuristic derived it from the letterhead layout.
Amber fallback default No content detected. Consider marking it.

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.

Brand your typography with CSS

The letterhead PDF supplies the visual identity (logo, header, footer). CSS supplies the typography: fonts, colors, spacing, table styling, heading treatment. Together they make one reusable brand identity that any Markdown document can be rendered through.

Full example — ~/.letterhead/company.css:

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; text-decoration: underline; }
code, pre   { font-family: "JetBrains Mono", ui-monospace, monospace; background: #f5f7fa; }
table th    { background: #0b3d91; color: white; }
table td    { border-bottom: 1px solid #e5e7eb; }
blockquote  { border-left: 3px solid #0b3d91; color: #4b5563; }

CSS is applied inside the safe area, so branded typography stays clear of your header, footer, and logo automatically. (CSS is applied by the WeasyPrint backend; the ReportLab fallback supports a reduced subset.)

Choose a blend strategy

Different letterheads need different overlay modes. Set with --strategy in the CLI, or when creating a droplet.

Strategy Best for
darken (default) Dark logo/artwork on light letterhead paper
multiply Watermark-like effects on subtle designs
overlay Better visibility across mixed contrasts
transparency Smooth blending with translucent layers
reverse Letterhead on top, content beneath

Multi-page letterheads

Different letterhead template per page position:

Letterhead PDF has… Applied to
1 page Every document page
2 pages Page 1 → first document page; page 2 → all others
3 pages Page 1 → first; page 2 → even; page 3 → odd

Advanced

  • Rendering backends. WeasyPrint (preferred, full CSS support) with a ReportLab fallback. Install brew install pango cairo fontconfig freetype harfbuzz to opt into WeasyPrint.
  • GitHub Flavored Markdown. Tables, task lists, strikethrough, code blocks with syntax highlighting — all supported when pycmarkgfm is available (it's a default dependency).
  • Custom overrides. mac-letterhead install --name X --letterhead /some/other.pdf --css /some/other.css for one-off droplets with non-conventional paths.
  • Publishing / release pipeline. Contributor-facing: docs/publishing.md.
  • Operator guide. For contributors: CLAUDE.md documents the architecture, release rules, and MCP registry constraints.

Privacy

Mac-letterhead runs entirely on your local machine. No network calls, no telemetry, no analytics, no cloud sync. See PRIVACY.md.

Contributing

See CONTRIBUTING.md.

License

MIT.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.24.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for easytoclaude from gravatar.com easytoclaude

Credits

Author: Erik

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev markdown mcp

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mac_letterhead-0.22.0.tar.gz (5.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mac_letterhead-0.22.0-py3-none-any.whl (2.4 MB view details)

Uploaded Python 3

File details

Details for the file mac_letterhead-0.22.0.tar.gz.

File metadata

  • Download URL: mac_letterhead-0.22.0.tar.gz
  • Upload date:
  • Size: 5.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mac_letterhead-0.22.0.tar.gz
Algorithm Hash digest
SHA256 6e15abfcbb816e0b98753c289f441bc855c1232adf6705f32b77df5a7ea06041
MD5 edf3f303b3161d426ac8e07cb064d0e7
BLAKE2b-256 7f6beb388617bb66f04fbce7b45d52323af428a147648fb562c40fbe397a88ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for mac_letterhead-0.22.0.tar.gz:

Publisher: publish.yml on easytocloud/Mac-letterhead

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mac_letterhead-0.22.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mac_letterhead-0.22.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5af22b097577f6e487ac4c71b7c275eef11b345bbb142630edbacbdafa741f2d
MD5 fe43f6279c1dee61459b195a6ac2d88c
BLAKE2b-256 9293f312f6fa323fde2eb22e7ace64bfe6a87c16d0b9f964e6f55c4912e0e39e

See more details on using hashes here.

Provenance

The following attestation bundles were made for mac_letterhead-0.22.0-py3-none-any.whl:

Publisher: publish.yml on easytocloud/Mac-letterhead

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.0

2 files

This release

0.22.0 This release

2 files

0.21.0

2 files

0.20.1

2 files

0.20.0

2 files

0.19.0

2 files

0.18.9

2 files

0.18.8

2 files

0.18.6

2 files

0.18.5

2 files

0.18.4

2 files

0.18.3

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.0

2 files

0.16.5

2 files

0.16.4

2 files

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.10

2 files

0.15.9

2 files

0.15.8

2 files

0.15.7

2 files

0.15.6

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.9

2 files

0.13.8

2 files

0.13.7

2 files

0.13.5

2 files

0.13.4

2 files

0.13.2

2 files

0.13.1

2 files

0.12.12

2 files

0.12.11

2 files

0.12.10

2 files

0.12.9

2 files

0.12.8

2 files

0.12.7

2 files

0.12.5

2 files

0.12.4

2 files

0.12.3

2 files

0.12.2

2 files

0.12.1

2 files

0.12.0

2 files

0.11.2

2 files

0.11.0

2 files

0.10.11

2 files

0.10.10

2 files

0.10.8

2 files

0.10.7

2 files

0.10.5

2 files

0.10.4

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.11

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

Yanked

0.6.4

2 files

Yanked reason: broken

Yanked

0.6.3

2 files

Yanked reason: broken dependencies when used with uvx

Yanked

0.6.1

2 files

Yanked reason: broken

Yanked

0.6.0

2 files

Yanked reason: broken

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page