quillpdf-mcp

quillpdf-mcp

MCP 用の PDF 操作ツールです。ローカルで PDF を操作するための MCP サーバー兼 CLI です。

• ページの結合、分割、整理、削除
• 回転、トリミング
• 透かし、ベイツ番号、ページ番号
• フォームのフラット化、画像 → PDF
• メタデータのクリーニング、ページ数の取得
• AES-256 による保護／ロック解除

pdf-lib を基盤にしています。MIT ライセンスです。stdio トランスポートを使用します。ネットワーク呼び出しはありません。ファイルがマシンの外に出ることはありません。

インストール

npx -p quillpdf-mcp quillpdf --help   # CLI
npx quillpdf-mcp --help               # MCP server (your MCP client launches it over stdio)

またはグローバルにインストールします。

npm install -g quillpdf-mcp
quillpdf --help

Node.js 18 以降が必要です。

対応範囲

quillpdf-mcp は、PDF の構造的な変換と AES-256 による保護／ロック解除に対応しています。OCR、墨消し、圧縮には対応していません。これらはブラウザ版（quillpdf.com）で利用でき、そちらも処理はクライアント側で完結します。完全にローカルで実行できるようになった機能のみ、こちらにも追加されます。

MCP クライアントから利用する

quillpdf-mcp は、あらゆる MCP クライアントで動作します。stdio サーバーのため、どのクライアントにも起動用のコマンドが必要です。次のサーバーエントリをクライアントの MCP 設定に追加してください。

{
  "mcpServers": {
    "quillpdf": {
      "command": "npx",
      "args": ["-y", "quillpdf-mcp"]
    }
  }
}

クライアントの例

このエントリを追加する場所です（最新の場所は、各クライアントのドキュメントを確認してください）。

• Claude Desktop — claude_desktop_config.json（Settings > Developer > Edit Config）。macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合：%APPDATA%\Claude\claude_desktop_config.json。上記と同じ mcpServers ブロックを使用します。(ドキュメント)

• Claude Code — claude mcp add quillpdf -- npx -y quillpdf-mcp を実行するか、プロジェクトルートの .mcp.json にブロックを追加します。(ドキュメント)

• Cursor — プロジェクト内の .cursor/mcp.json、またはすべてのプロジェクトで使う場合は ~/.cursor/mcp.json に設定します。同じ mcpServers ブロックを使用します。(ドキュメント)

• VS Code — ワークスペース内の .vscode/mcp.json に設定するか、プロファイルで MCP: Open User Configuration を実行します。VS Code では mcpServers の代わりに servers キーを使用し、"type": "stdio" を指定します。

  { "servers": { "quillpdf": { "type": "stdio", "command": "npx", "args": ["-y", "quillpdf-mcp"] } } }
  

  (ドキュメント)

その後、アシスタントに 「invoice-1.pdf と invoice-2.pdf を combined.pdf に結合して」 や 「discovery.pdf に、接頭辞 ABC で 1 から始まるベイツ番号を付けて」 のように依頼できます。アシスタントがマシン上のファイルパスを指定し、サーバーがファイルをローカルで読み書きします。

コピーしてすぐ使える設定が examples/mcp-config.json にあります。

ツール

ツール	機能
pdf_merge	2 つ以上の PDF を指定した順序で 1 つに結合します
pdf_split	ページ範囲で分割します（グループごとに 1 ファイル）。または、特定のページを 1 つのファイルに抽出します
pdf_rotate	ページを 90° の倍数で回転します（全ページまたは選択したページ）
pdf_watermark	すべてのページにテキストをスタンプします（サイズ／不透明度／色／位置）
pdf_bates	ベイツ番号を連番で付けます（接頭辞、開始番号、ゼロ埋め、角）
pdf_clean_metadata	Info 辞書のフィールドと日付を削除し、XMP メタデータストリームを削除します
pdf_page_count	ページ数を数えます
pdf_organize	指定した順序にページを並べます。並べ替え、削除、複製を一度に行えます
pdf_delete_pages	指定したページを削除し、残りを順序どおりに保持します
pdf_page_numbers	読みやすいページ番号（3、3 of 12、Page 3 of 12）をスタンプします。番号を付けない表紙も指定できます
pdf_crop	CropBox を設定してページの余白をトリミングします。非表示にするだけで、削除はしません（墨消しではありません）
pdf_flatten	入力済みフォームの値をページに描画し、編集やフォームデータとしての読み取りができないようにします
pdf_from_images	PNG／JPEG 画像から PDF を作成します（1 ページにつき 1 画像）
pdf_protect	AES-256 で暗号化し、文書を開く際にパスワードが必要になるようにします
pdf_unlock	パスワードを知っている文書からパスワードを削除します

コマンドラインから使う

# Merge (order is preserved)
quillpdf merge a.pdf b.pdf c.pdf -o combined.pdf

# Split into one file per range group → out-1.pdf (pages 1-3), out-2.pdf (page 5)
quillpdf split in.pdf --ranges "1-3,5" -o out.pdf

# Extract specific pages into a single file (reordering/duplicates allowed)
quillpdf split in.pdf --pages "5,1,1" -o extract.pdf

# Rotate every page 90°, or just some pages
quillpdf rotate in.pdf --angle 90 -o rotated.pdf
quillpdf rotate in.pdf --angle 180 --pages "2,4" -o rotated.pdf

# Watermark
quillpdf watermark in.pdf --text "DRAFT" --opacity 0.15 --position center -o wm.pdf

# Bates numbering → PLT-000001, PLT-000002, …
quillpdf bates in.pdf --prefix "PLT-" --start 1 --pad 6 -o numbered.pdf

# Strip document metadata
quillpdf clean-metadata in.pdf -o clean.pdf

# Page count (prints a number)
quillpdf page-count in.pdf

すべてのコマンドで --help を利用できます。

既存のファイルが黙って置き換えられることはありません。 -o のパスにファイルがすでに存在する場合、上書きせずにエラーでコマンドを停止します。意図的に置き換えるには、--force（または MCP ツールで force: true）を追加してください。

プライバシーとセキュリティに関する注意事項

• ローカルのみ。 すべての PDF 処理は、pdf-lib を通じてプロセス内で行われます。サーバーは標準入出力経由で通信し、ネットワーク接続を一切開きません。（MCP SDK にはオプションの HTTP/SSE トランスポートが node_modules に含まれていますが、このサーバーは標準入出力のみを使用するため、それらのコードが実行されることはありません。）
• パスワードで保護された PDF は拒否され、黙って解除されることはありません。 unlock 以外のすべての操作は、パスワードを勝手に取り除くのではなく、明確なメッセージを表示して停止します。unlock は、指定されたパスワードを使ってのみ復号します。パスワードの復元、推測、総当たりは行いません。
• 暗号化エンジン。 protect と unlock は、QPDF（Apache-2.0）を WebAssembly にコンパイルして、他のすべての処理と同様にオフラインでプロセス内実行します。pdf-lib は暗号化にまったく対応しておらず、暗号化機能を追加したコミュニティ製フォークもメンテナンスされていません。微妙なバグがあると、ロックされていると思っていた文書が実際にはロックされていないという事態につながるのは暗号化処理だけであるため、ここではリファレンス実装を使用しています。
• AES-256 のみ。 protect は PDF 2.0 の暗号化リビジョン 6 を出力します。40 ビットおよび 128 ビットのモードは意図的に公開していません。QPDF はどちらも暗号として脆弱と分類しており、実質的に保護されていないファイルを「保護済み」として提供するくらいなら、何も提供しないほうがよいためです。
• 権限フラグは要求であり、保証ではありません。 --no-print ／ --no-copy ／ --no-modify は、適切に動作するリーダーが尊重するビットを設定しますが、暗号化によって強制されるわけではありません。ファイルを実際に保護するのはパスワードです。（--no-copy を指定しても、アクセシビリティのための抽出は許可されるため、スクリーンリーダーは引き続き機能します。）
• クロップは墨消しではありません。 crop は CropBox を設定するため、トリミングされたコンテンツは非表示になりますが、ファイル内には残っており、完全に復元できます。機密情報を削除するために使用しないでください。
• clean-metadata の対象範囲。 文書情報辞書のタイトル、作成者、件名、キーワード、作成者ツールの各フィールドに加え、CreationDate／ModDate を消去します。さらに、Acrobat、Word、InDesign、LibreOffice が書き込む、文書レベルの XMP メタデータストリームも削除します。このストリームが正規のメタデータであることも少なくありません。保存時に pdf-lib が /Producer フィールドを独自の署名で書き換えるため、このフィールドは空にされるのではなく置き換えられる点に注意してください。ページレベルの注釈、埋め込みファイルの添付、ページのテキスト／画像コンテンツは消去しません。

まだ対応していない機能（ロードマップ）

これらの機能には Node の画像バックエンドまたは OCR エンジンが必要であり、後のリリースで対応する予定です。現時点ではこのパッケージに含まれていません。

• compress（画像の再エンコード）— sharp などの画像コーデックが必要です
• pdf-to-image（ページを PNG にレンダリング）— ラスタライザー（pdfjs-dist + canvas）が必要です
• redact（ラスタライズによる実際の墨消し）— 同じラスタライザーが必要です
• ocr（検索可能なテキストレイヤー）— tesseract.js が必要です

それぞれを追加すると、このパッケージの依存関係の規模はおよそ 4 倍になります。これらの機能を見送っている理由はそこにあります。このツールの売りは、小規模で、ローカルで動作し、ネットワーク接続を必要としないことです。この特長を損なわず、完全にローカルで実行できるようになった場合にのみ提供します。

基本方針

サーバーは小規模でローカルに動作し、監査しやすい状態を保ちます。多くの「PDF API」ツールは文書の処理に対して「こちらにアップロードしてください」と答えますが、法的証拠開示、医療記録、財務資料では、アップロードこそが問題です。このツールはお使いの環境で実行され、データはディスク上にとどまります。

開発

npm install
npm run build     # tsc → dist/
npm test          # builds, then runs the unit suite (node:test)

エンジン（src/core.ts）は純粋な処理を行い、バイト列を受け取ってバイト列を返します。入出力は行いません。CLI（src/cli.ts）と MCP サーバー（src/server.ts）は、その上に構築された薄いフロントエンドです。

ライセンス

MIT © Purple Directive。LICENSE をご覧ください。

詳しくは quillpdf.com をご覧ください。