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 (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:

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.

Per-document options via YAML front matter

Any Markdown file can start with a YAML front-matter block declaring per-document overrides — the same convention Jekyll, Hugo, and Obsidian use. Mac-letterhead reads it, applies the options, and renders the body normally.

---
title: Q3 Investor Update
output-dir: ~/Documents/investor
page-numbers: alternate
blend-strategy: multiply
author: Erik
---

# Q3 Investor Update

Executive summary…

Supported fields (all optional, kebab-case, unknown fields are logged and skipped):

Field Values Effect
title string PDF title metadata + auto-generated filename
output-dir path (supports ~) Where the resulting PDF is written
page-numbers bottom-right | bottom-center | bottom-left | alternate See below. Omit to disable page numbers entirely (the default).
blend-strategy darken | multiply | overlay | transparency | reverse Overrides the merge blend mode
style style name Overrides the letterhead style (ignored on dedicated MCP servers — see README_MCP.md)
author, subject string PDF metadata

page-numbers: alternate is designed for booklet-style multi-page letterheads: page 1 is treated as a title page (no number), subsequent left-hand pages get the number bottom-left, right-hand pages bottom-right. Requires the WeasyPrint backend.

Precedence (most-specific wins):

explicit CLI/MCP arg  >  front matter  >  server/droplet defaults  >  hard-coded

So if an MCP tool call passes output_path=… explicitly and the document says output-dir: …, the MCP arg wins. Front matter fills in what the caller left unspecified.

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:
Latest release

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.24.2.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.24.2-py3-none-any.whl (2.4 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: mac_letterhead-0.24.2.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.24.2.tar.gz
Algorithm Hash digest
SHA256 afd6e6b55ae0e110aa2c6cc5a3a11a72d63d09fb0011c58d02d1e1a062c672da
MD5 111b0a7338c2a38038326e0c505e5b61
BLAKE2b-256 73a4f42ceaf6b1faf19a532638707f09a37c9d9115ad130ecc6cbc260b3c83a1

See more details on using hashes here.

Provenance

The following attestation bundles were made for mac_letterhead-0.24.2.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.24.2-py3-none-any.whl.

File metadata

File hashes

Hashes for mac_letterhead-0.24.2-py3-none-any.whl
Algorithm Hash digest
SHA256 763e2bc9ed49b4b473ead6ac332c54657629018a9f65e9e64e7d40a2b80bc8b6
MD5 bbb230be00d3cf8b5fe42136eec9b195
BLAKE2b-256 18bcd0f8b8d13248229f0887b7d042deb80a44c4e31467e6fa14c94e1a73f520

See more details on using hashes here.

Provenance

The following attestation bundles were made for mac_letterhead-0.24.2-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

This release

0.24.2 This release

2 files

0.24.1

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

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