pdf-toolkit-mcp

免責事項。 pdf-toolkit-mcp は、独立したコミュニティ開発のオープンソースクライアントです。iLovePDF SL とは提携、推奨、後援、認定のいずれも受けていません。このプロジェクトは、お客様自身のプロジェクト認証情報を使用して、公開されている iLoveAPI REST サービスに接続します。プロキシ、再販、ライセンスの再付与は一切ありません。「iLovePDF」と「iLoveAPI」は iLovePDF SL の商標です。このプロジェクトは、これらの商標の所有権を主張しません。

📖 目次

• pdf-toolkit-mcp を選ぶ理由
• クイックツアー
• インストール
• ツール一覧
• ワークフローのレシピ
• アーキテクチャ
• 設定リファレンス
• セキュリティモデル
• 開発
• テストと CI
• リリース
• ロードマップ
• FAQ
• 貢献
• ライセンスと商標
• クレジット

🎯 pdf-toolkit-mcp を選ぶ理由

個人利用は無料です。 iLoveAPI の無料プランでは月あたり約 2,500 クレジットが付与されます。この MCP は MIT ライセンスで、費用はかかりません。

🚀 クイックツアー

インストール後は、Claude に話しかけるだけです。どのツールを呼び出すかはモデルが判断します。

You: Merge invoice-jan.pdf and invoice-feb.pdf into Q1.pdf, then compress it hard
     and lock it with the password "2026q1".

Claude (planning):
  1. merge_pdf     → invoice-jan.pdf + invoice-feb.pdf  →  Q1.pdf
  2. compress_pdf  → Q1.pdf                             →  Q1-compressed.pdf  (level: extreme)
  3. protect_pdf   → Q1-compressed.pdf                  →  Q1-compressed-protected.pdf

Claude (result):
  ✅ Created ~/docs/Q1-compressed-protected.pdf (312 KB, password-protected).

📦 インストール

前提条件

• Node.js ≥ 18（LTS 推奨）。
• iLoveAPI プロジェクトキー — developer.ilovepdf.com で無料プランを利用できます。所要時間は約 2 分です。
  1. サインアップ → プロジェクトを作成 → Project public key と Project secret key をコピーします。
  2. 環境変数に設定するか、クライアントの MCP 設定に追加します（以下の例を参照）。

オプション A — Claude Code（CLI のワンライナー）

export ILOVEAPI_PROJECT_PUBLIC_KEY="project_public_xxx"
export ILOVEAPI_PROJECT_SECRET_KEY="secret_key_xxx"

claude mcp add pdf-toolkit -- npx -y pdf-toolkit-mcp

Claude Code を再起動すると、18 個のツールがすべてピッカーに表示されます。/mcp で確認すると、pdf-toolkit: connected (18 tools) と表示されます。

オプション B — Claude Code プラグイン（pdf-workflow スキルを含む）

/plugin marketplace add EigenCharlie/pdf-toolkit-mcp
/plugin install pdf-toolkit@EigenCharlie/pdf-toolkit-mcp

このプラグインは MCP サーバーを自動設定し、Claude に PDF の代表的なマルチステップパイプラインを 5 つ教えるスキルもインストールします（ワークフローのレシピを参照）。

オプション C — Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "pdf-toolkit": {
      "command": "npx",
      "args": ["-y", "pdf-toolkit-mcp"],
      "env": {
        "ILOVEAPI_PROJECT_PUBLIC_KEY": "project_public_xxx",
        "ILOVEAPI_PROJECT_SECRET_KEY": "secret_key_xxx"
      }
    }
  }
}

オプション D — stdio 経由で任意の MCP クライアントを使用

ILOVEAPI_PROJECT_PUBLIC_KEY=… ILOVEAPI_PROJECT_SECRET_KEY=… npx -y pdf-toolkit-mcp

サーバーは stdio 経由で、標準の MCP JSON-RPC 2.0 フレーミングを使用します。Cursor、Windsurf、mcphub、mcp-inspector など、MCP に対応する任意のツールに接続できます。

オプション E — Claude Desktop .mcpb バンドル（ドラッグ＆ドロップ）

最新の GitHub リリースから pdf-toolkit-mcp-<version>.mcpb をダウンロードし、Claude Desktop の Settings → Extensions にドラッグします。Claude は、バンドルされたマニフェストの user_config セクションを通じて iLoveAPI キーの入力を求めます。npx も Node もターミナルも不要です。

バンドルには署名がありません（まだ発行者証明書がないため）。macOS Gatekeeper／Windows SmartScreen が初回インストール時に警告を表示する場合があります。承認する前に、リリースノートで SHA-256 を確認してください。

オプション F — MCP Registry（互換性のあるクライアントが自動検出）

このサーバーは、公式 MCP Registry に io.github.EigenCharlie/pdf-toolkit-mcp として登録されています。レジストリを参照できるクライアント（Claude Desktop の拡張機能パネル、VS Code の MCP ピッカー、mcphub など）では、手動設定なしでインストールできます。クライアントは npm パッケージを参照し、2 つの iLoveAPI 環境変数の入力を自動的に求めます。

🧰 ツール一覧

18 個すべてのツールは、厳密な Zod スキーマと additionalProperties: false を使用して公開され、text の概要と file:// リソース URI の両方を返すため、クライアントは出力を表示できます。

📚 整理

🔄 変換 — PDF から

🔄 変換 — PDF へ

✏️ 編集

🔐 セキュリティ

🩹 修復／OCR

すべてのツールで、input_file(s) には絶対パスまたは CWD からの相対パスを指定でき、output_path（ファイルまたはディレクトリ）も任意で指定できます。デフォルトでは、最初の入力ファイルと同じ場所にタイムスタンプ付きの名前で結果が保存されます。

🍳 ワークフローレシピ

同梱の pdf-workflow スキル（skills/pdf-workflow/SKILL.md）では、Claude による代表的な 5 つの複数ステップのパイプラインを紹介しています。手動で実行することもできます。完成後の状態を説明するだけで、Claude がツールを連続して実行します。

merge_pdf([a.pdf, b.pdf, c.pdf])
   → compress_pdf(level="recommended")
   → protect_pdf(password="…")

office_to_pdf(report.docx)
   → add_watermark(mode="text", text="CONFIDENTIAL", opacity=30)
   → protect_pdf(password="…")

extract_pdf_pages(scan.pdf, pages="3-9")
   → ocr_pdf(languages=["eng"])
   → pdf_to_word

compress_pdf(big.pdf, level="extreme")
   → protect_pdf(password="…")

repair_pdf(scan_broken.pdf)
   → ocr_pdf(languages=["eng"])
   → add_page_numbers(position="bottom-center")

🏛 アーキテクチャ

┌────────────────────────────┐    stdio    ┌──────────────────────────┐
│     Claude Code / Desktop  │◀───────────▶│   pdf-toolkit-mcp server │
│   (or any MCP client)      │  JSON-RPC   │   (this repo)            │
└────────────────────────────┘             └────────────┬─────────────┘
                                                        │
                                                        ▼
                                             ┌──────────────────────┐
                                             │  @ilovepdf/          │
                                             │  ilovepdf-nodejs     │
                                             │  (JWT + HTTP)        │
                                             └──────────┬───────────┘
                                                        │
                                                        ▼  HTTPS
                                             ┌──────────────────────┐
                                             │   iLoveAPI servers   │
                                             │   api.ilovepdf.com   │
                                             └──────────────────────┘

iLoveAPI の 5 フェーズのライフサイクル（src/api/tasks.ts でオーケストレーション）

  [ 10% ]   start     →  POST /v1/start/{tool}     (server assignment + task id)
  [ 40% ]   upload    →  POST /v1/upload           (one call per file, progress scales)
  [ 50% ]   process   →  POST /v1/process          (run the tool with params)
  [ 90% ]   download  →  GET  /v1/download/{task}  (bytes → Buffer)
  [100% ]   done      →  write to disk, emit file:// resource URI

サーバーは各境界で MCP の notifications/progress を送信するため、処理に時間がかかる操作（OCR、大規模な結合）でも、クライアントで進行状況バーをリアルタイムに表示できます。

プロジェクトの構成

pdf-toolkit-mcp/
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest
│   └── .mcp.json             # MCP server config (npx -y pdf-toolkit-mcp)
├── skills/
│   └── pdf-workflow/
│       └── SKILL.md          # 5-recipe skill for multi-step pipelines
├── src/
│   ├── index.ts              # #!/usr/bin/env node shebang
│   ├── server.ts             # MCP stdio bootstrap
│   ├── api/
│   │   ├── client.ts         # iLoveAPI client singleton (CJS interop via createRequire)
│   │   ├── tasks.ts          # 5-phase lifecycle orchestrator
│   │   ├── errors.ts         # HTTP → structured PdfToolkitError mapping
│   │   └── types.ts          # Types + error class
│   ├── tools/                # 18 tools, one file per concern
│   │   ├── _shared.ts        # Zod fragments + writeOutputAndReport helper
│   │   ├── merge.ts  split.ts  compress.ts
│   │   ├── convertFromPdf.ts convertToPdf.ts
│   │   ├── pageOps.ts  security.ts  watermark.ts
│   │   ├── repair.ts  ocr.ts
│   │   └── index.ts          # allTools[] barrel
│   └── util/
│       ├── paths.ts          # resolveInputs/resolveOutput + sandbox enforcement
│       ├── progress.ts       # Progress adapter
│       └── logger.ts         # stderr-only logger (stdio-safe)
├── tests/
│   ├── unit/                 # client, paths, errors, tools.merge (25 tests)
│   └── integration/          # smoke.test.ts — gated on iLoveAPI creds
├── scripts/
│   └── inspector.sh          # npm run inspect → MCP Inspector UI
└── .github/workflows/
    ├── ci.yml                # ubuntu+windows × node 18/20/22
    └── publish.yml           # Publishes to npm on v* tags with --provenance

⚙️ 設定リファレンス

環境変数

構造化エラーコード

すべてのエラーは、安定した機械可読コードを持つ PdfToolkitError として通知されます。

🔒 セキュリティモデル

pdf-toolkit-mcp は、開発者のマシンに安全にインストールできるよう設計されています。

• Stdio のみ。 サーバーはネットワークソケットを開かず、公式 SDK 経由で api.ilovepdf.com に HTTPS リクエストを送信するだけです。
• console.log は使用しません。 stdio 経由の JSON-RPC は、標準出力への書き込みが少しでもあると破損するため、すべてのログ出力は process.stderr を経由します。
• シークレットは永続化されません。 認証情報はプロセスの実行中、環境変数に保持され、ディスクやログファイル、ツールの応答に書き込まれることはありません。
• JWT はローカルで生成されます。 @ilovepdf/ilovepdf-nodejs SDK はシークレットキーを使用して JWT に自己署名するため、シークレットがマシンの外に出ることはありません。
• パスのサンドボックス化（任意）。 ILOVEAPI_SANDBOX_ROOT を設定すると、サーバーのアクセス先を単一のディレクトリツリーに制限できます。範囲外に解決されるパスは、API が呼び出される前にすべて例外になります。
• ツールごとの拡張子許可リスト。 html_to_pdf は .exe を拒否し、image_to_pdf は一般的なラスター形式のみを受け付けます。
• MIT ライセンスで監査しやすい設計。 TypeScript は約 2,000 行です。難読化や圧縮はなく、postinstall スクリプトもありません。

👩‍💻 開発

git clone https://github.com/EigenCharlie/pdf-toolkit-mcp.git
cd pdf-toolkit-mcp
npm install

よく使うタスク

Claude Code 内でのデバッグ

1. ローカルでビルドします：npm run build。
2. npm の代わりにローカルの dist を登録します：

   claude mcp remove pdf-toolkit    # if previously registered
   claude mcp add pdf-toolkit -- node "$(pwd)/dist/index.js"
   

3. Claude Code を起動する前に、シェルで PDF_TOOLKIT_DEBUG=1 を設定すると、詳細な stderr 出力が有効になります。
4. stderr の内容は claude mcp logs pdf-toolkit で確認できます。

✅ テストと CI

• ユニットテスト — client、paths、errors、tools.merge にわたる 25 件のテストです。すべてモック化されており、ネットワーク接続は不要です。npm test で実行します。
• インテグレーション・スモークテスト — tests/integration/smoke.test.ts は有効な最小構成の PDF を 2 つ作成し、実際の merge_pdf をエンドツーエンドでテストします。ILOVEAPI_*_KEY 環境変数が設定されている場合に実行され、セキュリティ上の理由から PR の CI では自動的にスキップされます。
• CI マトリックス — .github/workflows/ci.yml は、以下の環境で lint → typecheck → build → test を実行します。
  • OS：ubuntu-latest、windows-latest
  • Node：18、20、22

🚢 リリース

タグのプッシュ時に公開処理が自動実行されます。

npm version patch           # or minor / major
git push --follow-tags

その後、公開ワークフローが次の処理を行います。

1. lint、typecheck、build、テストを再実行します。
2. --access public --provenance（サプライチェーンの証明）を指定して npm に公開します。
3. 自動生成されたリリースノートを添えて GitHub Release を作成します。

必要なリポジトリシークレット：NPM_TOKEN（npm の自動化トークン）。

🗺 ロードマップ

• v0.1 — 18 個の PDF ツール、stdio トランスポート、プラグインとスキル、CI、npm 公開
• v0.1.1 — Claude Desktop 向け MCPB バンドル（.mcpb）、マーケットプレイスのマニフェスト、MCP Registry への登録（mcpName）
• v0.2 — Claude プラグインを anthropics/claude-plugins-official に提出し、画像ツールのコンパニオンパックを公開
• v0.3 — 8 個の画像ツール（サイズ変更、変換、圧縮、トリミング、回転、透かし、アップスケール、背景の削除）
• v0.4 — 署名ツール（署名ワークフローには有料プランが必要なため、環境変数フラグで制御）
• v1.0 — ホスト型／マルチユーザー環境向けの Streamable-HTTP トランスポート（任意）

機能の追加をリクエストする場合は、イシューを作成してください。

🙋 よくある質問

これは合法ですか／安全ですか／iLovePDFに許可されていますか？ はい。これは、お客様自身の認証情報を使用する軽量なオープンソースクライアントです。再販、再ライセンス、プロキシは一切行いません。iLoveAPIの利用規約では、ユーザーが提供するキーを使用するオープンソースライブラリが明示的に許可されています（コミュニティ製SDKのいくつかは、何年も前から公開されています）。このプロジェクトにはキーが含まれておらず、パッケージ名にも「iLovePDF」や「iLoveAPI」を使用していません。また、必要な免責事項も記載しています。

費用はかかりますか？ iLoveAPIでは、毎月約2,500クレジットが無料で提供されます（小規模な処理なら数千回分に相当します）。より負荷の高い用途には、有料のiLoveAPIプランが必要です。このMCP自体はMITライセンスで、永久に無料です。

オフラインで動作しますか？ いいえ。iLoveAPIはクラウド専用のため、すべてのツール呼び出しにインターネット接続が必要です。

特定のバージョンを指定できますか？ はい：claude mcp add pdf-toolkit -- npx -y [email protected]。

セルフホストできますか？ はい。リポジトリをクローンして、npm run buildを実行し、クライアントからnode ./dist/index.jsを指定してください。サーバーは完全にステートレスです。

iLoveAPIがダウンした場合はどうなりますか？ ツールはcode: "API_ERROR"およびdata.http_statusを含むPdfToolkitErrorを返します。Claudeはお客様に代わって、指数バックオフで再試行できます。

Claudeを使わずに利用できますか？ はい。Cursor、Windsurf、Zed、MCP Inspector、カスタムクライアントなど、MCP互換のクライアントであれば利用できます。サーバーは100％仕様に準拠しています。

🤝 コントリビューション

コントリビューションを歓迎します！PRを作成する前に、次の項目をご確認ください。

1. npm run lint && npm run typecheck && npm testを実行し、すべて成功すること。
2. 新しいツールは、src/tools/merge.tsのパターン（Zodスキーマ → runTask → writeOutputAndReport）に従うこと。
3. 少なくとも1つの単体テストを追加すること。
4. ツールを追加または改名した場合は、このREADMEのツールカタログを更新すること。

バグ報告も大歓迎です。ツール名、引数、および（安全に共有できる場合は）stderrの出力を記載してください。

📜 ライセンスと商標

MIT Licenseに基づき公開されています。© 2026 Carlos.

「iLovePDF」および「iLoveAPI」は、iLovePDF SLの商標です。このプロジェクトは独立したコミュニティ製クライアントであり、iLovePDF SLとの提携、同社による推奨、後援、認証を受けたものではありません。パッケージ名では、意図的に両方の商標を避けています。

🙏 クレジット

• iLovePDF / iLoveAPI — すべてのツール呼び出しを支えるクラウドPDF処理API。
• Anthropic — Claude、Claude Code、およびModel Context Protocol仕様の提供元。
• @modelcontextprotocol/sdk、Zod、Vitest、ESLint — このプロジェクトを支えるツールチェーン。
• 問題を報告し、ツールを提案し、プルリクエストを送ってくださるすべてのコントリビューター。🙌