pdf-extract-mcp

pdf-extract-mcp

デジタル（テキストレイヤー付き）PDF（銀行取引明細書、請求書、料金明細書）から表とテキストを抽出し、自動でPIIをマスキングして CSV / JSON / Excel に出力する Model Context Protocol（MCP）サーバーです。

invoice-extractor 製品の一部です。このパッケージはMCPの配布チャネルです（「エコシステムに寄生する存在」：1つのバックエンドで多様なホストのワークフローに対応）。Webデモは親プロジェクトにあります。

できること

• extract_pdf — デジタルPDF（base64またはURL）をアップロードし、構造化された表の行をCSV / JSONレコード / XLSXで取得します。
• health — サービスの状態と無料枠の上限を確認します。

表の検出では、ページごとに3つの方法を試します。罫線付きの表 → ヘッダー行自体のx座標から列を明示的に導出（グリッド線のない明細書PDFに対応。欧米の銀行では一般的です）→ 汎用的なテキスト配置。

PIIのマスキング（デフォルトで有効）では、次の情報を対象とします。

地域	マスキング対象
米国／国際	SSN、EIN/TIN、IBAN、SWIFT/BIC、ルーティング番号／ABA、口座番号、カード番号（通常の形式と 4111 1111 1111 1111 ／ハイフン区切りの形式）、米国および国際電話番号、メールアドレス
中国	18桁／15桁の国民ID、携帯電話番号、銀行カード、USCC（统一社会信用代码）、パスポート、2～3文字の個人名、組織を示すキーワード

番号だけでは判別しにくい銀行識別番号（ルーティング番号／口座番号／ソートコード）は、ラベルに続く場合に限りマスキングされます。そのため、照会番号や金額は読み取れる状態に保たれます。金額、日付、摘要は変更されません。

スキャンされたPDFや画像のみのPDFは、明示的に拒否されます（SCANNED_PDF_UNSUPPORTED）。無料枠で対応するのはデジタルPDFのみです（OCRは有料枠の候補です）。

制限（無料枠）

• クライアントごとに、30日間のローリング期間で100ページ（匿名、クライアントのハッシュで識別）。
• ファイルあたり50 MB。
• 上限を超えると、ツールはアップグレード案内を含む構造化された QUOTA_EXCEEDED 応答を返します。請求が通知なく発生することはありません。
• PDF_EXTRACT_API_KEY に有料キーを設定すると、クォータを回避できます（課金ゲートウェイはP1項目です。現在の無料枠では有料キーは発行されていません）。

実行（ローカルstdio — Claude Desktop / Cursor / 任意のMCPクライアント）

pip install -e .
pdf-extract-mcp

クライアント設定の例：

{
  "mcpServers": {
    "pdf-extract": {
      "command": "pdf-extract-mcp",
      "env": {}
    }
  }
}

実行（リモートのstreamable-http、ホスト型MCPクライアント向け）

REMOTE_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=5060 \
  python -m pdf_extract_mcp.server
# POST JSON-RPC to http://127.0.0.1:5061/mcp

ツールスキーマ

extract_pdf(
  pdf_base64: str | None,     # preferred: PDF bytes as base64
  pdf_url:    str | None,     # alternative: direct https .pdf URL
  output:     "csv"|"json"|"xlsx",   # default csv
  redact_pii: bool = true,
  api_key:    str | None,    # paid key, optional
) -> {
  ok, type: "tables"|"text", pages, tables, rows, columns,
  csv | rows_json | xlsx_base64,   # depends on output
  elapsed_ms
}

テレメトリ

すべての呼び出しは、ベストエフォートで（抽出を妨げることなく） ~/.cache/pdf-extract-mcp/mcp_usage.jsonl に追記されます（PDF_EXTRACT_STATE_DIR で変更できます）。クライアントはソルト付きハッシュとして記録されます。PDFの内容やPIIがログに記録されることはありません。

注：配布されるstdioバンドルでは、このファイルはユーザーのマシンに保存されるため、配布元は読み取れません。実際の外部利用状況は、ホスティングレジストリのオーナーAPIから取得します（Smitheryでは GET /servers/{namespace}/{name}/logs を実行すると呼び出し回数が返されます）。

技術スタック

mcp >= 1.2（mcp 1.xのFastMCPとmcp 2.xのMCPServerの両方で動作）、pdfplumber、openpyxl。pandasは任意です。インストールされていない場合、パッケージは軽量な行のリスト形式の表にフォールバックします（標準ライブラリのCSV/JSONとopenpyxlを使用）。これにより配布バンドルを小さく保てます。Python 3.10以降。

ライセンス

MIT