Mac-letterhead

A macOS utility that turns your letterhead PDF into drag-and-drop apps and CLI tools for creating professional, branded PDFs from existing PDFs or Markdown.

Get started View on GitHub

What Mac-letterhead does

Letterhead apps for macOS

Create drag-and-drop applications that automatically apply your company letterhead to PDFs or Markdown documents. Drop a file on the app, get a professional PDF out.

Markdown to PDF

Convert Markdown into beautifully formatted PDFs that respect your letterhead margins, typography, and branding. Supports tables, code blocks, lists, and GitHub Flavored Markdown when available.

Advanced rendering pipeline

Uses WeasyPrint for high-quality HTML+CSS rendering when system libraries are available, and ReportLab as a pure-Python fallback. Both paths are covered by an extensive test suite.

Quick start on macOS

1

Requirements

  • macOS
  • Python 3.10 or higher
  • uv package manager
  • Optional (WeasyPrint): brew install pango cairo fontconfig freetype harfbuzz
2

Create a letterhead app

# Basic application using ~/.letterhead/company.pdf uvx mac-letterhead install --name "company" # Use custom letterhead and CSS uvx mac-letterhead install \ --name "Technical Reports" \ --letterhead /path/to/letterhead.pdf \ --css /path/to/styles.css
3

Use from the command line

# Merge a PDF with letterhead uvx mac-letterhead merge letterhead.pdf "Output" ~/Desktop document.pdf # Render Markdown to a letterheaded PDF uvx mac-letterhead merge-md letterhead.pdf "Output" ~/Desktop document.md

AI & MCP integration

Mac-letterhead ships with an MCP (Model Context Protocol) server so AI tools like Claude can generate letterheaded PDFs directly from natural language prompts.

🤖

Start the MCP server

# Generic multi-style server uvx mac-letterhead[mcp] mcp # Dedicated single-style server uvx mac-letterhead[mcp] mcp \ --style easytocloud \ --output-dir ~/Documents/generated-pdfs
🛠️

Available tools (high level)

  • create_letterhead_pdf – render Markdown as a letterheaded PDF
  • merge_letterhead_pdf – apply letterhead to existing PDFs
  • analyze_letterhead – inspect margins and printable areas
  • list_letterhead_templates – list available styles