JustFill PDF Form Automation

JustFill MCP サーバー

AI エージェント（Claude、ChatGPT、n8n — あらゆる MCP クライアント）が、justfill.app を通じて PDF フォームのフィールドを検出、確認、入力できるようにします。

ChatGPT で PDF フォームに入力する

公開されている JustFill PDF Forms プラグインをインストールして ChatGPT のプラグインディレクトリから追加し、JustFill アカウントを接続してください。このホスト型の方法では、Python クライアントのインストールや MCP サーバーの手動設定は不要です。

1 ページ、6 フィールドのサンプルで、次のプロンプトを試してください。

Use JustFill to open https://justfill.app/examples/chatgpt/project-intake.pdf.
List its fields and show a preview. Do not fill anything yet.

架空の値を使った入力済みプレビューを依頼し、PDF を生成する前に承認してください。確認済みのレイアウトを保存し、次のクライアントやプロジェクトでは、同じ元の空白 PDF を開いてください。保存したテンプレートは同じ JustFill アカウントで利用でき、生成ファイルにはそのアカウントのプランが適用されます。

2 つのプロジェクトの例を試して、編集可能な実際の結果をダウンロードしてください。 この例には、架空の 2 人のクライアント向けのプロンプト、空白の PDF、無料出力の透かしが入った 2 つの生成 PDF が含まれています。

ホスト型サーバー — ローカルインストール不要

MCP クライアントが OAuth 対応のリモートサーバーをサポートしている場合は、次のサーバー URL を使用してください。

https://justfill.app/api/mcp

クライアントから接続し、JustFill にサインインして、アクセス要求を確認してください。この方法では、Python パッケージのインストールや API キーのコピーは不要です。 アクセスは JustFill の「アカウント → API キー」から取り消せます。

接続ガイド。 クライアントは MIT ライセンスで提供されています。PDF 処理には JustFill アカウントの利用枠が使われます。 まず空白のフォームと架空の値で試し、エクスポート前に入力済みプレビューを確認してください。確認済みのレイアウトを保存しておけば、同じフォームを再び使う際に新しいデータを入力できます。

Excel または CSV の一括ワークフロー

元データがすでにスプレッドシートにあり、既存の同じ PDF に各行の内容を入力したコピーが 1 つずつ必要な場合、MCP クライアントは必須ではありません。ガイド付きのブラウザーワークフローでは、XLSX または CSV をインポートし、列を確認済みの PDF フィールドに対応付け、各レコードをプレビューして、承認済みの PDF を ZIP でエクスポートできます。

5 行の PDF 差し込み印刷サンプルをお試しください — クレジットカードも営業担当者との通話も不要です。

インポート可能な n8n ワークフロー

このリポジトリにある決定論的なワークフロー JSONから始めてください。 PDF と JSON ペイロードを受け取り、そのフォーム専用に保存された確認済みフィールド名を再利用し、元のレイアウトに入力して、一時ダウンロードリンクを返します。

このワークフローはn8n テンプレートライブラリに掲載されています。 新たに実行する際は、このリポジトリにある最新の厳密なマッピング用 JSON をインポートしてください。合成フィクスチャと検証の証跡も含まれています。 ワークフローは無料でダウンロードできます。実行には JustFill アカウントと PDF 処理の利用枠が必要です。別の JustFill コミュニティノードではなく、組み込みノードを使用します。

このリポジトリには、決定論的なワークフロー JSON の実体、合成テスト PDF、本番環境での証跡のほか、未知のフォーム向けの独立した 2 パスのビジョンワークフローも含まれています。どちらも標準の HTTP Request ノードを使ってホスト型 MCP エンドポイントを呼び出すため、認証情報を追加する前に内容を確認できます。

ソースワークフローと証跡を確認するか、n8n の手順に沿ったセットアップガイドをご覧ください。

ビジネス事例：定期的なサプライヤー情報の取り込み

オペレーションチームは、サプライヤー指定の取り込み用 PDF を変更せずに保管し、レビュー済みのフィールドレイアウトを一度保存しておけば、n8n で Webhook または CRM レコードから承認済みのベンダーデータを正確なフォームにマッピングできます。ワークフローは一時的な入力済み PDF のリンクを返すため、Drive にアップロードしたり、下書きメールに添付したり、ベンダーレコードに書き戻したりする前に確認できます。リポジトリに含まれる合成サプライヤー情報取り込み用 PDF で、顧客データを使わずにこの一連の流れを試せます。

Gemini CLI 拡張機能

同じレビュー済み MCP ツールと、付属の PDF ワークフローガイダンスをインストールします。

gemini extensions install https://github.com/mrmaciej1/justfill-mcp

拡張機能のマニフェストはリポジトリのルートにあり、公開済みの justfill-mcp パッケージを使用します。有効化する前に、Gemini CLI で通常のサードパーティ拡張機能の同意が求められます。

エージェントが信頼できる理由

ソース	信頼度	説明
保存済みテンプレート	1.0	この PDF には以前入力した実績があり、レイアウトは人間／エージェントが確認済みです。ML は一切実行されません。
AcroForm	1.0	PDF に埋め込みフォームフィールドがあり、ファイルから読み取ってネイティブに入力します。
ML による検出	0.0–0.95	正直なドラフトです。視覚的に確認し（render_preview）、修正してから save_template で確定します。

ML の信頼度は較正済みです。検出器の生スコアは確率ではありません（サーバー側のフィルターは生スコア約 0.02 からボックスを受け入れ、生スコア 0.15 で自動的に受け入れます）。そのため、期待どおりの意味になるよう 0～1 に対応付けられています。≥0.75 は「検出器が確信している」、0.4～0.75 は「おそらく正しいので、プレビューをざっと確認」、<0.4 は「境界的な判定なので、確認してください」という意味です。生の検出器スコアは各フィールドの raw_score に保持されます。

修正ループ（render_preview → add/update/remove_field）があるのは、ML による検出には誤検出や検出漏れがあるためです。誤検出はコストになりません（未入力のままにするか、削除できます）。検出漏れはプレビューで確認でき、add_field を一度呼び出すだけで修正できます。レビュー後に save_template を実行すると、そのフォームへの以後の入力はすべて決定論的になります。

ローカルクライアントの設定

uv tool install justfill-mcp

一度認証します（ブラウザーが開き、justfill.app にログインした状態でワンクリックします）。

justfill-mcp login

その後、設定に認証情報は一切不要です。

{
  "mcpServers": {
    "justfill": { "command": "justfill-mcp" }
  }
}

インストール不要の設定にするには、uvx を直接使用します。

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

代替手段は、サーバーが確認する順に次のとおりです。

1. JUSTFILL_API_KEY 環境変数 — justfill.app → Account → API Keys でキーを作成し、設定に "env": {"JUSTFILL_API_KEY": "jf_live_…"} を追加します。
2. justfill-mcp login で保存したキー（~/.config/justfill/credentials.json）。
3. JUSTFILL_EMAIL + JUSTFILL_PASSWORD — 旧式のフォールバックです。API キーのほうが適しています（設定ファイルにパスワードを記載せずに済み、クライアントごとに取り消し可能で、セッション中に期限切れになりません）。

ツール

• open_pdf(path, min_confidence=0.0, max_pages=10, force_detect=False) — テンプレート → AcroForm → ML の順に解決します。スキャン画像にも対応しています （jpg/png/tiff → PDF に決定論的に変換されるため、テンプレートも引き続き 一致します）。force_detect=True を指定すると、保存済みテンプレートを無視して ML を再実行します。
• render_preview(page_index) — ラベル付きフィールドボックスを表示したページ画像（青 = 決定論的、緑／オレンジ／赤 = ML の信頼度）
• render_filled_preview(values, page_index) — 値を所定の位置に 描画した同じページ（チェックボックスには X が入ります）。 入力コストはかかりません — 入力前に確認してください。
• list_fields(page_index?)
• add_field(x, y, w, h, name, page_index, field_type, align?, vertical_align?) — 座標はページに対する割合、原点は左上
• update_field(field_id, …) / remove_field(field_id)
• update_fields([{field_id, …}, …]) / remove_fields([ids]) — 一括処理版
• prune_fields(field_type?, confidence_below?, width_below?, height_below?, page_index?, exclude_ids?) — 1 回の呼び出しで検出ノイズを一括削除します（条件は AND で結合され、削除された ID が返されます）。
• fill_pdf(values, output_path, flatten=True) — values = {field_id: text}; 収まるように縮小／切り詰められる値については、warnings で通知します。
• save_template(name) — レビュー済みのレイアウトを保存し、決定論的な再入力に使用します。
• list_templates()

テキストの配置：align = left|center|right、vertical_align = top|middle|bottom — フィールドごとに設定します（例：RTL フォームでは right、枠付きの数字では center）。 テンプレートに保存されます。

エージェントのフロー例

open_pdf("~/forms/w-9.pdf")            → acroform, 27 fields, confidence 1.0
fill_pdf({"f1": "Jane Doe", …}, "~/out/w-9-filled.pdf")

open_pdf("~/forms/scan.jpg")           → converted to PDF; ml, 34 fields
render_preview(0)                      → agent sees noise + one missed line
prune_fields(field_type="cell", width_below=3)   → 16 removed in one call
add_field(x=18, y=62.5, w=40, h=3, name="Phone")
render_filled_preview({…})             → values sit right, no overflow
fill_pdf({…}, "~/out/filled.pdf")
save_template("Client intake form")    → next time: deterministic

注意事項

• 認証には通常の justfill.app アカウントを使用します。トークンは有効期限が切れると自動更新されます。
• 使用状況とドキュメント出力のルールは、Web アプリと同じアカウントサービスによって適用されます。fill_pdf は出力がクリーンか、透かし入りかを報告します。
• サーバーセッションごとに開ける PDF は一度に 1 つです（設計上の仕様です — ID の安定性を保つためです）。
• このリポジトリは、リリース済みバージョンの MCP クライアントをミラーしています（開発は justfill.app バックエンドとともに、非公開のモノレポで行われています）。こちらのイシュートラッカーでのバグ報告や機能リクエストを歓迎します。