pdf-mcp

pdf-mcp

PDF や Word 文書の表を Excel、CSV、または JSON に変換します。 エージェントのセットアップが不要なシンプルなブラウザーアプリを使うか、同じ決定論的な抽出ツールをMCP経由で AI エージェントに接続できます。

ブラウザーアプリは、表を直接変換するためのものです。抽出した行をプレビューし、基本的な構造上の警告を強調表示します。ファイルはお使いのコンピューター内に保持されます。さらに高度なプロファイルチェックでは、名前付きフィールドの検証、元データの証拠の保持、繰り返し発生する文書ワークフローでの accepted、needs_review、rejected の判定が可能です。セルの値は文書パーサーから取得され、生成されたモデルの出力ではありません。

実際の文書向けのプロファイルと測定済みのベースラインが必要ですか？Document Reliability Pilotをご覧ください。エージェントは、構造化されたオファーoffers/document-to-excel-pilot.jsonを利用できます。

ウェブサイト：シンプルな変換、ローカルツール、無料のホスト型エージェントベータ版。

現在の制限事項： PDF の抽出は、デジタル生成された文書に対応しています。スキャンした PDF や画像のみの PDF には OCR が必要ですが、これは含まれていません。accepted という判定は、設定されたチェックに合格したことを意味します。元の文書自体が正しいことを証明するものではありません。

シンプルなブラウザーアプリ

pdf-mcp を使う最も簡単な方法です。アプリをダウンロードした後は、Python、ターミナル、MCP クライアント、エージェントの設定は必要ありません。

1. v0.4.0 リリースを開きます。
2. 64 ビット版 Windows、Apple silicon 搭載 Mac、または 64 ビット版 Linux 用の pdf-mcp-app ZIP をダウンロードします。
3. ZIP を展開し、pdf-mcp-app を開きます。
4. ブラウザーが開きます。PDF または Word 文書をドロップし、Excel、CSV、または JSON を選択して、文書を変換をクリックします。

使い終わったら、ブラウザーでアプリを停止をクリックしてください。アプリはお使いのコンピューター上でのみ待ち受けます。一時的な文書のコピーは変換直後に削除され、作成されたダウンロードファイルは 30 分後、またはアプリの停止時に期限切れとなります。コミュニティベータ版のダウンロードには現在署名がないため、開くことを確認するようオペレーティングシステムから求められる場合があります。

Python がすでにインストールされている場合は、同じインターフェースを次のコマンドで起動できます。

python -m pip install "pdf-agent-mcp @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"
pdf-mcp-app

シンプルなアプリは、表をそのまま抽出します。「基本的な構造上の問題は検出されませんでした」という表示は、正確性を保証するものではありません。重要な値は使用前に確認するか、繰り返し発生する業務ワークフローにはプロファイルチェック付きのパイロットをご利用ください。

エージェント向け：ローカル版または無料ホスト型ベータ版

通常の pdf-agent-mcp コマンドは、引き続きローカルで動作し、MIT ライセンスで、ネットワーク接続もテレメトリも使用しません。 測定を行うエージェントベータ版を明示的に希望する場合は、pdf-agent-cloud-mcp が認証済みの 1 回の処理に限り、選択したドキュメントのみをアップロードします。

プロファイルのチェックと評価は、現在ローカル版または有料パイロットの一環として実行されます。 無料ホスト型ベータ版で現在利用できるのは、生テキスト、テーブル、CSV の抽出のみです。

エディション	ドキュメントの保存場所	測定	最適な用途
ローカル版 pdf-agent-mcp	お使いのマシン上に保存	なし	機密文書、または制限のないローカル利用
ホスト型 pdf-agent-cloud-mcp	一時的な認証済みアップロード	範囲を限定した運用カウンター	匿名化済み／非機密データでのベータ評価

無料ホスト型ベータ版では、暦月あたり 25 回まで処理できます。一時アップロードは各リクエストの完了時に削除されます。 使用状況のメトリクスには、ファイル名、ドキュメントの内容、抽出テキスト、テーブルのセルは含まれません。 エンドポイントのデプロイ完了に向けて、現在申し込みを受け付けています。ドキュメントを添付せずにお申し込みください。エンドポイントの検証後に招待を開始します。

無料エージェントベータ版の利用を申し込む

承認後、受け取ったエンドポイントとキーを使って、別のブリッジをインストールして設定してください。

python -m pip install "pdf-agent-mcp[cloud] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"

{
  "mcpServers": {
    "pdf-cloud": {
      "command": "pdf-agent-cloud-mcp",
      "env": {
        "PDF_MCP_CLOUD_URL": "https://endpoint-provided-with-beta-access.example",
        "PDF_MCP_CLOUD_API_KEY": "key-provided-once"
      }
    }
  }
}

匿名化済みまたは非機密のファイルのみを使用してください。 無料ベータ版の利用規約、プライバシーに関する通知、および機械可読形式の beta/free-hosted-beta.json をご覧ください。

ドキュメントから作成できるもの

次のような PDF または Word のテーブルを：

Item     Qty   Price
Widget    3    12.50
Gadget    1    40.00
Bolt     10     0.25

invoice-lines-v1 に照らして確認し、明示的な判定とともに正規化されたレコードとして返せます。

{
  "decision": "accepted",
  "profile": {"id": "invoice-lines-v1", "version": "1.0.0"},
  "records": [
    {
      "values": {"item": "Widget", "quantity": "3", "unit_price": "12.50"},
      "evidence": {
        "item": {"page": 1, "table_index": 0, "row": 1, "column": 0, "bbox": [242.9, 136.0, 287.7, 154.0]}
      }
    }
  ]
}

エージェントに提供するツール

ツール	機能
list_extraction_profiles()	組み込みのプロファイル ID、バージョン、フィールド、ハッシュ
extract_with_profile(path, profile)	正規化されたレコード、セルの根拠情報、検証上の問題、およびフェイルクローズの判定
export_with_profile(input_path, profile, output_path)	プロファイルで検証された .xlsx、.csv、または .json。XLSX には Review、Data、Evidence の各シートが含まれます
page_count(path)	PDF のページ数
extract_text(path, page)	ページごとのテキスト（1 ページ、またはドキュメント全体）
extract_tables(path, page, merge_multipage)	生の行、ソース座標、および基本的なパーサー警告
table_to_csv(path, page, index)	1 つのテーブルを整形済み CSV テキストに変換
extract_docx_text(path)	.docx ファイルの段落テキスト
extract_docx_tables(path)	Word のテーブルをセルの行として抽出。同じ評価フィールドと結合セルの警告を含みます
docx_table_to_csv(path, index)	1 つの Word テーブルを整形済み CSV テキストに変換
export_document_tables(input_path, output_path, merge_multipage)	PDF／DOCX のテーブルを .xlsx、.csv、または .json にエクスポート

Claude Desktop の MCP 設定

最も手軽に使う方法は、Claude Desktop のような MCP クライアントを使用することです。手順は 3 つです。

1. インストールする

python -m pip install "pdf-agent-mcp[mcp] @ https://github.com/wesseltl/pdf-mcp/releases/download/v0.4.0/pdf_agent_mcp-0.4.0-py3-none-any.whl"

2. クライアントの設定に追加する

Claude Desktop の設定ファイルは次の場所にあります。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

サーバーを追加します。

{
  "mcpServers": {
    "pdf": { "command": "pdf-agent-mcp" }
  }
}

3. Claude Desktop を再起動します。 ツールアイコンが表示され、サーバーが接続されたことを確認できます。

これで完了です。お使いのマシンにある任意の .pdf または .docx について質問できます。

You:  Check /Users/me/invoices/2024-001.pdf with invoice-lines-v1.

Agent (calls extract_with_profile):
  decision: accepted
  records: 3
  issues: 0

エージェントは、needs_review および rejected の結果を、信頼できる業務データとして扱わず、人による確認に回す必要があります。

ファイルアクセスの制限： エージェントが 1 つのフォルダー以外を読み取れないようにするには、 PDF_MCP_ALLOWED_DIR を設定してください。SECURITY.md をご覧ください。

他の MCP クライアントで使用する

同じサーバーをあらゆる MCP クライアントで使用できます。異なるのは設定だけです。コマンドとして pdf-agent-mcp を使用してください。

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）。Claude Desktop と同じ形式で、ホットリロードに対応しています（再起動不要）。

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json。キーが異なる点（mcpServers ではなく servers）と、type が必須である点に注意してください。ツールを実行できるのは Copilot の エージェントモード のみです。

{ "servers": { "pdf": { "type": "stdio", "command": "pdf-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（存在しない場合は作成してください）。Claude Desktop と同じ形式です。

{ "mcpServers": { "pdf": { "command": "pdf-agent-mcp" } } }

Cline — VS Code の拡張機能にある MCP 設定パネルから追加してください（コマンド：pdf-agent-mcp）。

プロファイルで検証する抽出

このパッケージには、参照プロファイルとして lab-coa-v1 と invoice-lines-v1 が含まれています。

extract-document-with-profile examples/invoice.pdf invoice-lines-v1 result.xlsx

終了ステータスは、accepted の場合は 0、needs_review の場合は 2、rejected の場合は 3 です。XLSX 出力には Review、Data、Evidence の各シートが含まれます。数式のような文書内の値は、実行されないようにスプレッドシートへのエクスポート時にエスケープされます。

プロファイルは、バージョン管理された通常の JSON 契約です。プロファイル形式と 機械可読スキーマを参照してください。結果は、バージョン管理された 抽出結果スキーマに従います。

プロファイルを評価する

ローカルに保存された、顧客が承認した期待値の行と照合して、フィールドおよびレコードの正確性を測定します。

evaluate-document-profile evaluations/sample-invoice.json

レポートには文書のハッシュと集計指標が含まれますが、文書の内容や期待値のセルの値は含まれません。付属のサンプルは合成データです。実際の文書群に対する正確性を主張する前に、代表性のある非公開データセットを作成してください。評価ガイドを参照してください。

より大規模なデモとして、リポジトリには18 文書の架空のワークフローシミュレーションが含まれています。PDF と DOCX の各種形式で、受理、レビュー、却下の結果を検証します。これは製品開発者が作成した回帰テスト用のカバレッジであり、顧客による検証や需要の証拠ではありません。

生データのエクスポート

文書からファイルへ直接変換するワークフローには、CLI を使用します。

export-document-tables report.pdf report.xlsx
export-document-tables coa.docx coa.xlsx
export-document-tables coa.docx coa.json

生の Excel エクスポートには、表の位置とパーサーの警告を記載した Review シートが含まれます。ワークフローで標準フィールドと受理判定が必要な場合は、プロファイルベースのエクスポートを使用してください。

出力について

extract_tables は、生の行データと簡易的なパーサー診断情報を返します。

{
  "page": 1,
  "rows": [ ... ],
  "n_rows": 4,
  "looks_clean": true,
  "column_count": 3,
  "empty_ratio": 0.0,
  "warnings": []
}

• looks_clean — これらの基本的な診断で問題が見つからなかったことだけを示す true です。正確性のスコアでも受理判定でもありません。
• column_count — すべての行で列数が一致する場合の列数です（行ごとに異なる場合は null）。
• empty_ratio — 空白セルの割合です。値が高い場合、抽出がうまくいっていないことがよくあります。
• has_merged_cells — セルが結合されている表を示す、Word 専用のフラグです。Word は結合セルを繰り返し値として公開するため、その表にはレビュー用のフラグが付けられます。
• warnings — 平易な表現で示されるフラグです。例：「不揃い：行の列数が [2, 3, 4] です（グリッドを誤検出した可能性があります）」、または 「セルの 66% が空です」。PDF の表は、入れ子や結合セル、複数ページにまたがる場合など、実際に扱いが難しいため、ツールは無理に問題がないように見せかけず、結果に疑いがある場合にその旨を知らせます。

通常の Python からも使用可能

from pdf_mcp import docx_extractor, exporter, extractor, verified

result = verified.extract_with_profile("invoice.pdf", "invoice-lines-v1")
if result["decision"] == "accepted":
    rows = [record["values"] for record in result["records"]]

verified.export_with_profile("coa.pdf", "lab-coa-v1", "coa.xlsx")

extractor.extract_tables("invoice.pdf")      # {'tables': [{'rows': [...], 'looks_clean': True, ...}]}
extractor.table_to_csv("invoice.pdf")        # clean CSV of the first table
extractor.extract_text("report.pdf", page=1)

docx_extractor.extract_docx_tables("coa.docx")
docx_extractor.docx_table_to_csv("coa.docx")

exporter.export_document_tables("coa.docx", "coa.xlsx")

テスト

python -m pip install -e ".[test]"
python -m unittest discover -s tests     # builds synthetic PDFs, runs anywhere
evaluate-document-profile evaluations/sample-invoice.json
evaluate-document-profile evaluations/simulated-customer/development.json
evaluate-document-profile evaluations/simulated-customer/holdout.json

ライセンス

MIT