pdfedit-mcp

@niubai/pdfedit-mcp — エージェントから既存の PDF を編集

PDF Edit API を使う 5 つの MCP ツールです。すでに存在する PDF 内のテキストの置換、削除、墨消し、挿入、フォームへの入力を行い、元のフォント、元のレイアウト、指定していないすべての内容をそのまま維持します。「似た見た目の新しい PDF を生成」するのではなく、指定した単語を変更した同じファイルと、変更箇所ごとの変更前・変更後の画像を返します。

PDFEDIT_BASE_URL を設定しない場合、サーバーはホスト型 API https://api.niubai.vip に接続します。別のデプロイ先を指定するには、値を設定してください。

キーなしで 30 秒で試す

PDFEDIT_API_KEY を設定しない場合、サーバーはキー不要の無料プランで動作します。IP アドレスごとに 1 日 20 ページまで利用でき、出力には TEST の透かしが入ります。ローカルファイルも利用できます。

Claude Code

claude mcp add pdfedit -- npx -y @niubai/pdfedit-mcp

Cursor / VS Code / Claude Desktop — このサーバーエントリー（またはリポジトリページのボタン）を使用します。

{ "pdfedit": { "command": "npx", "args": ["-y", "@niubai/pdfedit-mcp"] } }

次に、エージェントにこう依頼します。「./contract.pdf の 'Acme Ltd' を 'Acme GmbH' に置き換えて、IBAN を墨消ししてください。」 編集済みの PDF は元のファイルと同じ場所に書き込まれ、変更箇所ごとの変更前・変更後の画像が返されます。無料の API キー（1 か月に 200 ページまで。通常の文書には透かしなし）は、https://api.niubai.vip でメールアドレスを入力するだけで取得できます。

インストール

Claude Code — 1 行でインストールできます。

claude mcp add pdfedit -e PDFEDIT_API_KEY=sk_live_your_key -- npx -y @niubai/pdfedit-mcp

Cursor — ディープリンクを使用します（Settings → MCP でも同じ JSON を設定できます）。

cursor://anysphere.cursor-deeplink/mcp/install?name=pdfedit&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBuaXViYWkvcGRmZWRpdC1tY3AiXSwiZW52Ijp7IlBERkVESVRfQVBJX0tFWSI6InNrX2xpdmVfeW91cl9rZXkifX0=

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "pdfedit": {
      "command": "npx",
      "args": ["-y", "@niubai/pdfedit-mcp"],
      "env": {
        "PDFEDIT_API_KEY": "sk_live_your_key"
      }
    }
  }
}

キーがない場合は、env を省略してください。キー不要の無料プランでは、IP アドレスごとに 1 日 20 ページまで利用でき、出力には TEST の透かしが入ります。ローカルサーバーを実行できない Web クライアント（claude.ai）では、代わりにホスト型エンドポイントを追加できます。PDF の URL のみを受け付けます。

ローカルファイルと URL

このパッケージはお使いのマシンで実行されるため、各ツールの file 引数には絶対パス（または ~）でローカルパスを指定できます。ファイルは自動的にアップロードされ、編集済み PDF は入力ファイルと同じ場所に <name>.edited.pdf として書き込まれます。また、https:// URL または前回の呼び出しで取得した f_… ファイル ID も指定できます。ホスト型の Streamable-HTTP エンドポイントはローカルディスクを読み取れないため、その旨を伝えます（remote server cannot read local paths; pass a URL）。いずれの場合も PDF が MCP コンテンツのブロブとして送信されることはありません。変更されたページのプレビュー PNG のみ、最大 3 枚がインラインで返されます。

ツール

ツール	説明
pdf_edit	置換、削除、墨消し、挿入、入力を 1 回の呼び出しで行い、プレビューも返します。
pdf_batch	1 つのテンプレートに対し、レコードごとに同じ編集を行います。ジョブ ID を返します。
pdf_find	ページ、bbox、フォント、スパン ID を含むすべてのスパンを返します。4 つの照合モードで絞り込めます。
pdf_preview	ページ（または領域）を PNG として描画し、必要に応じてハイライトボックスを表示します。
pdf_job	非同期編集またはバッチ処理の結果を返します。

各スキーマはゲートウェイの OpenAPI ドキュメントから生成されるため、ここでの edits[] エントリーは POST /v1/edit および SDK が受け取るものと同じです。詳細はsrc/tools.tsを参照してください。

拒否される操作とその理由

エンジンは、編集済みに見えても実際には編集されていないファイルを返すより、理由を添えて「いいえ」と返すことを優先します。拒否には 2 種類あります。

検証ゲート — 編集が試みられ、ロールバックされました

すべての変更は書き込まれた後に検証され、保持するか取り消すかが決まります。いずれかのゲートで失敗したグループはロールバックされ、failed[] に報告されます。

理由	発生したこと
collateral_damage	書き換え対象の領域外でピクセルが変化しました。ページ上の別の要素が移動しています。ページはバイト単位で元の状態に復元されます。
readback_failed	編集した矩形を再読み込みしたところ、そこにあるはずのテキストが返されませんでした。
does_not_fit	置換テキストが領域に収まらず、fit による悪化の許可もありませんでした（fit: "strict"）。または、すでにテキストがある場所に挿入しようとしました。
font_unavailable	options.font.policy: "exact_only"（または "metric_only"）が指定されており、システムにもドキュメントにも使用可能な書体がありません。
redact_residual	墨消し後も矩形内で文字列が読み取れました。処理済みとは報告せず、削除を拒否します。
no_target、field_not_editable、field_value_invalid、field_value_mismatch	フォームフィールドが存在しない、読み取り専用である、値を受け付けない、または書き込んだ値を読み戻せませんでした。

options.atomic（既定値）が指定されている場合、1つでも失敗するとリクエスト全体が失敗し、ファイルは生成されません。options.strict も、編集が単に一致しなかった場合に同様の動作をします。一致しなかった編集には、何もせずに終わるのではなく、あいまい一致による suggestions（「Acme, Inc. のことですか？」など）が返されます。

現時点で未対応 — invalid_request として事前に拒否

ドキュメントに触れる前に API が拒否する内容：

• find での右から左に書くテキスト（アラビア語、ヘブライ語）。マッチング後の処理はすべて左から右に進みます。行は左端から組み立てられ、置換テキストは右方向に配置されるため、RTL のテキストは視覚的に逆向きの行と照合され、間違った方向に書き込まれても後続処理で検出できません。
• スキャン画像のピクセルにしか存在しないテキストに対する redact。 単語そのものが画像であるため、覆い隠してもファイル内に残り、操作の保証を果たせません。
• fit: "reflow" と併用した style。 リフローではドキュメント独自の書体で段落全体が再組版されるため、マッチしたフレーズは個別にスタイルを適用できるまとまりではなくなります。
• redact または form に対する fit: "reflow"。
• options.preview: "pages"（ページ全体のプレビュー）。"changes" と "none" は使用できます。
• 不明な操作。

既知の制限 — サポートされていますが、知っておくべき注意点があります

• ラスター画像への OCR 書き込みでは、テキストではなく画像が生成されます。 スキャンされた行に複製できる元のテキストがない場合、新しい文字はピクセルとして描画されます。ページ上では正しく表示され、再レンダリングで検証されますが、その後は選択も検索もできません。
• スキャン画像の墨消しは、テキストレイヤーとピクセルの消去によって検証されます。 出力を再認識して検証するわけではありません。
• 相対位置に配置されたテキスト — matplotlib は各目盛りを直前の目盛りを基準に書き込みます — が原因で、無関係な要素が数百ポイントも移動することがあります。エンジンはこれを副次的な損傷と判断し、変更をロールバックします。ページは正しい状態のままですが、編集は行われません。回帰テスト用に、コーパス内の 1 つのファイルで意図的にこの動作を発生させています。
• フォント。 置換フォントは、ファイルに十分なフォントデータが埋め込まれている場合（そのフォントのサブセットがどのページに含まれていても該当します）はドキュメント自体のフォントに、埋め込まれていない場合はメトリクス互換フォント（Arial、Helvetica、Times New Roman、Courier New、Calibri、Cambria、Georgia、Segoe UI、Palatino、Book Antiqua、Bookman、Century Gothic、Avant Garde、New Century Schoolbook、Arial Narrow にはすべて互換フォントがあります。幅が同じなので、行末の位置も変わりません）に設定されます。どちらも使えない場合は、最後の手段として同じクラスの類似フォントを使用します。結果には常に使用したフォント（font_source、font_used）が示され、最後の手段を使用した場合は概要に approx_font_used が明記されます。また、options.font.policy: "metric_only" を指定すると、類似フォントは一切使用されません。そのため、「少し見た目が違う」という結果も、予期しない事態ではなく確認可能な情報として示されます。
• ラジオグループとコンボボックスの flatten は、ファイルに含まれる外観情報によって動作が決まります。処理が行われない場合、フィールドは有効なまま残り、失敗する代わりに flatten_skipped の警告が表示されます。
• 暗号化されたドキュメントでは、開くためのパスワード（password）が必要です。パスワードがない場合、編集は試行されません。

詳細情報

• クイックスタート — クライアントごとのインストール方法、エージェントへの指示方法、返される内容。正式な使い方のドキュメントです。この README は意図的に簡潔にしています。
• API リファレンス — edits[]、options、レスポンスのすべてのフィールド。
• 例 — 変更前と変更後の 10 組。それぞれに、結果を生成したリクエストが含まれています。
• リポジトリ — このサーバー、SDK、ホスト型エンドポイントのソースコード。

MIT。API の基盤となるエンジンは AGPL-3.0 です。API は GET /source を通じて、利用者に完全なソースコードを提供します（どのキーでも利用でき、無料のテストキーも含まれます。ホスト型 MCP エンドポイントでは https://pdfedit-mcp-remote.niubai-pdfedit-remote-worker.workers.dev/source から取得できます）。