Mac-letterhead

Mac-letterhead

Markdown ファイルを手作業で書式設定することなく、会社のレターヘッド入りのプロ品質 PDF に変換します。 Mac-letterhead はレターヘッド PDF を デジタル便箋 として扱います。ページの安全領域（ヘッダー、フッター、ロゴに重ならない領域）に Markdown を印刷し、短い CSS ファイルを使ってブランドのタイポグラフィを適用します。

すべて Mac 上で実行されます。ドラッグ＆ドロップアプリ、コマンドラインツール、Claude やその他の AI クライアントから直接呼び出せる Model Context Protocol サーバーで、同じエンジンを利用できます。

---

• できること
• インストール
• クイックスタート（2 分）
• 使い方 — ドロップレット · CLI · MCP サーバー
• 設定と微調整 — ブランド CSS · ブレンド方法 · 複数ページ
• 上級者向け · プライバシー · ライセンス

できること

会社のレターヘッド、つまり上部にロゴ、下部に連絡先情報、場合によっては控えめな透かしが入った PDF があるとします。作成する文書も、そのレターヘッド入りにする必要があります。提案書、レポート、請求書、メモなどです。

従来の方法はどれも面倒です。位置がなかなか合わない Word テンプレート、デザイナーの InDesign ファイルへのコピー＆ペーストと調整の繰り返し、PDF エディターでレターヘッドの上に手作業でテキストを配置する方法などです。あるいは、ブランド要素のない文書を送るしかありません。

Mac-letterhead はこれらすべてを自動で行います。レターヘッド PDF を分析して安全な印刷領域を見つけ（ヘッダー、フッター、ロゴの周囲のスペース）、ブランドのタイポグラフィ（小さな CSS ファイルに記述したフォントと色）を使って、その領域に Markdown を描画し、完成した PDF を出力します。複数ページのレターヘッドや、1 ページ目とそれ以降のページの違いにも対応しています。

同じツールに 3 つのインターフェースが用意されています。Mac のドラッグ＆ドロップアプリ（個人での利用向け）、コマンドラインユーティリティ（スクリプト向け）、MCP サーバー（Claude やその他の AI クライアントがリクエストに応じてブランド入り文書を作成するためのもの）です。

インストール

次のいずれかを選んでください。

Homebrew（Macでの日常的な使用におすすめ）：

brew tap easytocloud/tap
brew install mac-letterhead

uvx（永続的なインストール不要。uv の一時的な環境を使用）：

uvx mac-letterhead --help

Claude Desktop（ダブルクリックでインストール）： リリースページから最新の mac-letterhead-<version>.mcpb をダウンロードしてダブルクリックしてください。あとは Claude for macOS が処理します。

システム依存関係（任意ですが推奨）

最高のレンダリング品質（WeasyPrint による CSS の完全サポート）を得るには、WeasyPrint のシステムライブラリを一度インストールしてください。

brew install pango cairo fontconfig freetype harfbuzz

これらがない場合、Mac-letterhead は自動的に ReportLab に切り替わります。よりシンプルな出力になり、外部依存関係は不要で、すべての機能が引き続き動作します。

クイックスタート（2 分）

1. Mac-letterhead が見つけられる場所にレターヘッドを置きます。 デフォルトの規則では ~/.letterhead/<name>.pdf を使用します。

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

2. （任意ですが、強く推奨）タイポグラフィを追加します。 ブランドのフォントと色を設定した ~/.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; }
   

   これを省略すると、Mac-letterhead はすっきりとしたデフォルト設定を使用します。

3. デスクトップにドロップレットを作成します。

   mac-letterhead install --name "company"
   

   デスクトップに company.app が表示されます。

4. 任意の .md または .pdf ファイルをドロップレットにドロップします。 保存先を選ぶと、レターヘッド付きの PDF が作成されます。

以上です。以降の書類は、ドロップするだけで作成できます。

使用方法

同じエンジンを、3 つのインターフェイスで利用できます。

🖱️ ドラッグ＆ドロップ式ドロップレット

Macでの人間向けワークフローに最適です。一度設定すれば、以降はデスクトップアイコンに書類をドラッグするだけです。

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

各ドロップレットは完全な macOS .app バンドルです。ドラッグして移動したり、Dock に追加したり、Automator のワークフローに組み込んだりできます。ファイルをドロップすると、出力先を選択する保存ダイアログが開きます。

ドロップレットをダブルクリック（何もドロップせずに）すると、そのドロップレットのレターヘッドのセーフエリアプレビューが表示されます。裁ち落としマーク、色分けされた網掛け、ソースラベルを含む PDF が 1 つ生成され、デフォルトのビューアで開きます。Markdown が想定どおりの位置に配置されるか、統合前に確認するのに便利です。

⌨️ コマンドライン

スクリプト作成、CI、または一度限りの変換に最適です。ドロップレットは不要です。

# 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

詳細なリファレンス：mac-letterhead --help。

🤖 AI クライアント向け MCP サーバー

Claude、Claude Code、Cursor、Windsurf、またはその他の AI アシスタントに、ブランドに合わせた書類をオンデマンドで作成させたい場合に最適です。

Claude Desktop の設定（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

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

その後、Claude に「会社のレターヘッドで第 3 四半期の投資家向けアップデートを作成して」と依頼します。Mac-letterhead が書式を整え、PDF を ~/Desktop に保存します。

公式 MCP レジストリに io.github.easytocloud/mac-letterhead として公開されており、Glama と PulseMCP からも確認できます。MCP の設定全般（スタイル別サーバー、1 つのクライアントから複数のブランドを利用する方法）については、README_MCP.md をご覧ください。

設定と微調整

安全領域をプレビューして指定する

Mac-letterhead は、レターヘッド上のどこにコンテンツを印刷しても 安全 か、つまりヘッダー、フッター、ロゴの間のスペースを把握する必要があります。次の 3 段階で判定します。

1. 明示的に指定します。 Preview.app でレターヘッドを開き（ツール → マークアップツールバーを表示 → 長方形）、目的の安全領域を囲むボックスを描いて保存します。これで完了です。Preview.app では注釈にラベルを付ける方法がないため、Mac-letterhead はラベルがなくても、ページ上の単一の四角形注釈を安全領域として扱います。明確に指定したい場合（またはラベル付けに対応した PDF エディターを使用している場合）は、長方形をクリックして → サイドバー → 説明 → safe-area（または printable-area。大文字と小文字を区別せず、部分一致）と入力します。これで、ページごとに複数の長方形を使えるようになり、ラベルが付いたものだけが使用されます。
2. 自動検出します。 注釈がない場合、Mac-letterhead はレターヘッドのレイアウト（テキスト、図形、ロゴ）を分析し、それらを避けた安全な長方形を約 40 pt の安全余白を設けて割り出します。
3. 既定値にフォールバックします。 コンテンツが検出されない場合は、すべての辺に 1 インチの余白を設定します。

いつでも判定結果をプレビューできます。

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

プレビュー PDF は色分けされているため、ツールの判定への確信度をひと目で確認できます。

色	判定元	意味
緑	annotation	指定した領域がそのまま採用されています。
スレートブルー	auto-detected	レターヘッドのレイアウトからヒューリスティックに割り出されています。
アンバー	fallback default	コンテンツが検出されていません。領域の指定を検討してください。

各角のトンボにより、印刷に適した精度を実現しています。ごく淡い色合いで領域を塗りつぶし、全体像を把握しやすくしています。左下の小さなラベルには、結果の判定元と安全領域の正確な寸法が表示されます。

YAML フロントマターによるドキュメント単位のオプション設定

Markdown ファイルの先頭に YAML フロントマターブロックを記述すると、ドキュメント単位のオーバーライドを指定できます。Jekyll、Hugo、Obsidian と同じ規約です。Mac-letterhead はこれを読み取り、オプションを適用して、本文を通常どおりレンダリングします。

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

# Q3 Investor Update

Executive summary…

対応フィールド（すべて任意、ケバブケース。未知のフィールドはログに記録され、スキップされます）。

フィールド	値	効果
title	文字列	PDF のタイトルメタデータと自動生成されるファイル名
output-dir	パス（~ に対応）	生成される PDF の出力先
page-numbers	bottom-right | bottom-center | bottom-left | alternate	詳細は以下を参照してください。省略するとページ番号は完全に無効になります（既定値）。
blend-strategy	darken | multiply | overlay | transparency | reverse	マージのブレンドモードをオーバーライドします
style	スタイル名	レターヘッドのスタイルをオーバーライドします（専用 MCP サーバーでは無視されます。README_MCP.md を参照してください）
author, subject	文字列	PDF メタデータ

page-numbers: alternate は、小冊子形式の複数ページのレターヘッド向けに設計されています。1 ページ目はタイトルページとして扱われ（番号なし）、以降は左ページの左下、右ページの右下に番号が付きます。WeasyPrint バックエンドが必要です。

優先順位（最も具体的な設定が優先されます）。

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

つまり、MCP ツールの呼び出しで output_path=… が明示的に渡され、かつドキュメントに output-dir: … と記載されている場合は、MCP 引数が優先されます。フロントマターは、呼び出し元が指定しなかった項目を補います。

CSS でタイポグラフィにブランドを反映する

レターヘッド PDF がビジュアルアイデンティティ（ロゴ、ヘッダー、フッター）を担い、CSS が タイポグラフィ（フォント、色、間隔、表のスタイル、見出しのデザイン）を担います。これらを組み合わせることで、あらゆる Markdown ドキュメントのレンダリングに使える、再利用可能なブランドアイデンティティを作成できます。

完全な例 — ~/.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 は安全領域内に適用されるため、ブランドに合わせたタイポグラフィはヘッダー、フッター、ロゴに自動的に重ならないよう配置されます。（CSS は WeasyPrint バックエンドで適用されます。ReportLab のフォールバックでは、対応する機能が一部に限られます。）

ブレンド戦略を選ぶ

レターヘッドによって、適したオーバーレイモードは異なります。CLI で --strategy を指定するか、ドロップレットの作成時に設定します。

戦略	適した用途
darken（デフォルト）	明るいレターヘッド用紙に暗いロゴやアートワークを重ねる
multiply	控えめなデザインに透かしのような効果を加える
overlay	コントラストが混在する場合に視認性を高める
transparency	半透明のレイヤーを滑らかにブレンドする
reverse	レターヘッドを上に、コンテンツを下に配置する

複数ページのレターヘッド

ページ位置ごとに異なるレターヘッドテンプレートを適用します。

レターヘッド PDF のページ数…	適用先
1 ページ	すべての文書ページ
2 ページ	1 ページ目 → 文書の最初のページ、2 ページ目 → それ以外すべて
3 ページ	1 ページ目 → 最初、2 ページ目 → 偶数ページ、3 ページ目 → 奇数ページ

高度な機能

• レンダリングバックエンド。 WeasyPrint（推奨、CSS を完全サポート）と、フォールバック用の ReportLab を使用します。WeasyPrint を有効にするには、brew install pango cairo fontconfig freetype harfbuzz をインストールしてください。
• GitHub Flavored Markdown。 pycmarkgfm が利用可能な場合、テーブル、タスクリスト、取り消し線、構文ハイライト付きコードブロックをすべてサポートします（デフォルトの依存関係です）。
• カスタムオーバーライド。 慣例に沿わないパスを使うドロップレットを一時的に作成するには、mac-letterhead install --name X --letterhead /some/other.pdf --css /some/other.css を実行します。
• 公開／リリースパイプライン。 コントリビューター向けの説明は、docs/publishing.md をご覧ください。
• 運用ガイド。 コントリビューター向けに、CLAUDE.md でアーキテクチャ、リリースルール、MCP レジストリの制約について説明しています。

プライバシー

Mac-letterhead はすべてローカルマシン上で動作します。ネットワーク通信、テレメトリー、分析、クラウド同期は一切ありません。PRIVACY.md をご覧ください。

貢献

CONTRIBUTING.md をご覧ください。

ライセンス

MIT。