facturas-inbox-mcp

facturas-inbox-mcp

スペインの業務書類のフォルダーを、AI エージェントが推論できる、検証済みの構造化データに変換するMCPサーバーです。各 PDF（請求書、訂正請求書、レシート、給与明細、AEAT 様式など）を分類し、請求書の項目（NIF/CIF、課税標準額、税率ごとの IVA、IRPF、合計）を抽出して、計算と納税者番号のチェックサムを検証し、四半期ごとの IVA 控除額／納付額を算出します。

ローカルでオフライン動作します。API キーは不要です。指定されたフォルダーのみを読み込みます。

スペインの一般的なgestoríaの業務向けに作られています。クライアントが1か月分の PDF をフォルダーに入れ、担当者が内容や計算の正誤、VAT の納付状況を確認します。

30秒のデモ

Claude Code と Sonnet で、合成データのexamples/inbox（誤った合計、レシート、クレジットノート、給与明細、modelo 303、スキャンしたページを含む11件の書類）を指定します。実際のセッションです。回答は長さを抑えるために短縮しています（編集していない全文はdocs/demo-transcript.mdをご覧ください）。

> I'm the bookkeeper for Gestoría Demo Ficticia SL (CIF B87654323). Process the invoice
  inbox and tell me our IVA position for Q3 2026, and flag anything I need to look at
  by hand. Answer in English, briefly.

  ⏺ facturas - scan_folder {}
  ⏺ facturas - vat_summary {"own_tax_id":"B87654323","quarter":"2026-Q3"}
  ⏺ facturas - validate_tax_id {"tax_id":"B87654323"}

Q3 2026 IVA position: €243.00 to pay (a pagar), provisional.

- IVA repercutido: €504.00, from 1 issued invoice (GD-2026-0088, base €2,400 at 21%)
- IVA soportado: €261.00, from 4 received documents (base €1,400): €231 at 21% and
  €30 at 10%
- The July papelería invoice (€52.50 IVA) is cancelled out by the September credit note.

Check by hand:
1. Papelería PE-2026/0455 (30 Jul): the total says €1,250 but base + IVA comes to
   €1,210. Excluded. If the supplier corrects it, your position drops to about €33.
2. Gasolinera ticket 88213 (14 Aug, €60): IVA not broken out and no recipient NIF.
   Excluded. Probably not deductible without a full invoice.
3. Scanned PDF (5 Sep): no text layer, so it needs OCR or a manual read. It could be
   a missing Q3 invoice.
4. Credit note PE-2026/R-0019: classified at 0.69 confidence. Confirm it really is a
   rectificativa of PE-2026/0412.
5. Laura's advisory invoice (3 Aug): €150 IRPF withheld, which goes on modelo 111,
   not the IVA return.
   …

**5ターン・23秒・$0.13。**すべての数値はツールの結果に基づいており、モデルが計算したものではありません。検証に失敗した書類は除外され、理由とともに一覧表示されるため、気付かないまま集計に含まれたり、除外されたりすることはありません。

ツール

ツール	説明	ヒント
scan_folder	フォルダー内のすべての書類を分類・抽出し、書類ごとに簡潔な行で表示します。limit／cursorでページ分割できます	読み取り専用
classify_document	1件の書類にラベルを付け、信頼度スコアとラベルの根拠となるシグナルを表示します	読み取り専用
extract_invoice	請求書番号、日付、発行者／受取人のNIF、課税標準額、VAT明細、IRPF、合計に加え、すべての相互検証結果を返します。response_format: concise | detailed	読み取り専用
validate_tax_id	NIF／NIE／CIFのチェックサムを検証します。誤りがある場合は正しい制御文字を示します	読み取り専用
vat_summary	quarter（2026-Q3）またはfrom／toの期間を指定して、税率ごとのIVA納付額と控除額を、除外対象の一覧とともに表示します	読み取り専用
export_csv	スキャン結果を新しい.csvファイルに書き込みます（区切り文字は;、小数点はカンマ。スペイン語版Excelでそのまま開けます）。上書きはしません	新規ファイルを書き込み

すべてのツールはoutputSchemaを公開し、structuredContentを返します。SDKは両方向を検証します。すべてのツールに完全なアノテーション（readOnlyHint、destructiveHint: false、idempotentHint、openWorldHint: false）が設定されているため、クライアントは読み取り専用のツールを自動承認できます。

検証項目

extract_invoiceは、すべての検証に合格した場合のみstatus: "ok"を返します。

検証項目	ルール
issuer_tax_id	クライアント欄より前に、チェックサムが有効なNIF／NIE／CIFが記載されている
issue_date	実在する日付が見つかった（15/07/2026、22 de septiembre de 2026など）
vat_rate_standard	すべてのVAT税率がスペインの税率（0、4、5、10、21 %）である
vat_math	請求書で課税標準額が税率ごとに分かれている場合、課税標準額 × 税率 = VAT（±1セント）
irpf_math	課税標準額 × IRPF税率 = 源泉徴収額（±1セント）
total_math	課税標準額 + VAT − IRPF = 合計

すべての計算は整数のセント単位で行われます。

インストール

Node.js 20.12以降が必要です。

30秒で試す（同梱のサンプルデータ）

claude mcp add facturas-demo -- npx -y facturas-inbox-mcp --demo

--demoを指定すると、パッケージに同梱された合成データの受信フォルダーを提供します。その後、Claudeに次のように尋ねてください。 「CIF B87654323の会社の経理担当です。2026年第3四半期のIVA納付状況はどうなっていますか。また、手作業で確認すべき点は何ですか？」

Claude Code

claude mcp add facturas -- npx -y facturas-inbox-mcp ~/Documents/facturas

Claude Desktop

claude_desktop_config.jsonに次の内容を追加します（Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "facturas": {
      "command": "npx",
      "args": ["-y", "facturas-inbox-mcp", "/Users/you/Documents/facturas"]
    }
  }
}

その他の MCP クライアント

標準の stdio サーバーです。npx -y facturas-inbox-mcp <folder> [more folders…] または npx -y facturas-inbox-mcp --demo を実行します。フォルダーは FACTURAS_INBOX_DIRS（PATH と同じ区切り文字）から指定することもできます。

サンプルの受信フォルダーを使ってソースから実行する

git clone https://github.com/pedrozapatadev/facturas-inbox-mcp && cd facturas-inbox-mcp
npm install && npm run build
claude mcp add facturas -- node "$PWD/dist/index.js" "$PWD/examples/inbox"

次のように質問します。「CIF B87654323 の記帳担当者です。2026 年第 3 四半期の IVA の状況を教えてください。」

LLM を使わずにツールを試すには、npm run inspect（MCP Inspector）を実行します。

設計上の決定

• 決定論的なコアで、モデルを内蔵しません。 エージェントはすでに言語モデルです。不足しているのは、信頼できる回答を返すツールです。抽出はルールベースで行い、すべての結果に根拠（分類器のシグナル、チェックの詳細、警告）が付随します。サーバーは自身の処理を説明でき、同じ入力には常に同じ出力を返します。
• 黙って失敗せず、明確に失敗します。 見つからなかったフィールドは推測せず、null になります。チェックに失敗した書類は合計から除外され、その理由とともに一覧表示されます。エラーは、呼び出しを修正する方法（「force: true を渡して続行を試してください」「先に OCR を実行してください」）を示す isError 結果として返されます。
• トークン効率に優れています。 scan_folder はコンパクトな行を返し、ページネーションに対応しています。extract_invoice はデフォルトで簡潔です。export_csv はデータではなく、パスと件数を返します。
• ファイルシステムをサンドボックス化しています。 パスは realpath で解決され、起動時に指定されたフォルダー内に収まる必要があります。そのため、../ による移動や、フォルダー外を指すシンボリックリンクは拒否されます（テスト済みです）。書き込みを行うのは export_csv のみで、新しい .csv ファイルを作成し、既存のファイルを上書きすることはありません。
• 書類のテキストは信頼できないものとして扱います。 サーバーの指示では、書類内にある指示に従わないようエージェントに伝えています。生テキストは要求された場合のみ untrusted_text_preview のラベルを付けて返します。=, +, -, @ で始まる CSV セルは、スプレッドシートの数式インジェクションを防ぐため無効化されます。エクスポートファイルは 0600 の権限で作成されます。
• 書類ごとの処理量に上限があります。 ファイルサイズは 20 MB、PDF は 200 ページまでです。解析前にテキストは 1M 文字で切り詰められます。抽出用正規表現は線形時間で処理されます。ReDoS のケースには回帰テストがあります。
• 脅威モデル。 攻撃者が制御できるのは書類の内容であり、ファイルシステムではありません。存在しないパスとフォルダー外のパスには同じエラーが返されるため、このツールを使って別の場所に何があるか調べることはできません。すでに受信フォルダーへの書き込み権限を持つユーザーが、チェック後の読み取り前に競合を発生させる可能性（TOCTOU の時間差）はありますが、これは対象範囲外です。
• stdout はプロトコルです。 ログはすべて stderr に出力されます。エンドツーエンドテストでは、ビルド済みバイナリを実際の stdio 経由で実行します。余計な console.log があればテストは失敗します。

制限事項

対象範囲を正直に示します。これは会計ソフトではなく、ショーケース規模のツールです。

• PDF にはテキストレイヤーが必要です。 スキャン画像は unreadable として報告され、OCR のヒント（例：ocrmypdf）が示されます。OCR は内蔵されていません。
• ヒューリスティックによる抽出は、スペインで一般的な請求書レイアウト（Base imponible、IVA 21 %、Total factura などのラベル付きフィールド）に合わせて調整されています。一般的でないレイアウトは、誤った結果ではなく needs_review として返されます。
• 現時点で未対応： recargo de equivalencia、EU 域内取引／リバースチャージ請求書、Facturae XML、取引先名（税務 ID のみ対応）。
• チェックサム検証のみです。 有効な NIF は形式が正しいことを示しますが、AEAT または VIES への登録は確認されません。
• 電子請求書発行や VeriFactu 用のツールではありません。 受領した書類を読み取るもので、請求書の発行や申告書の提出は行いません。vat_summary は確認用の暫定数値であり、modelo 303 ではありません。

開発

npm install
npm run fixtures    # regenerate examples/inbox (synthetic data, valid-checksum fictional IDs)
npm run typecheck
npm test            # unit + in-memory MCP client + stdio end-to-end (build first for the e2e)
npm run build
npm run inspect     # MCP Inspector UI against the sample inbox

src/
  index.ts        stdio entry point, CLI args → allowed folders
  server.ts       the six tools: schemas, annotations, error mapping
  schemas.ts      zod input/output schemas
  pipeline.ts     read → classify → extract, shared by all tools
  classify.ts     rule-based document classifier with explainable signals
  extract.ts      invoice field extraction + arithmetic checks
  taxid.ts        NIF / NIE / CIF validation
  amounts.ts      Spanish amounts and dates, in integer cents
  vat-summary.ts  repercutido / soportado aggregation
  documents.ts    sandboxed filesystem + PDF text extraction
  csv.ts          Excel-friendly CSV export
test/             MCP-level tests (in-memory client, stdio e2e, sandbox escapes)

公式の MCP TypeScript SDK v2（@modelcontextprotocol/server）、 zod、unpdf を基盤としています。

リリース

1. package.json の version と server.json の両方の version フィールドを更新します。
2. npm publish を実行します（先にビルドとテストが実行されます。npm の 2FA が必要です）。
3. gh workflow run publish-mcp-registry.yml を実行すると、GitHub OIDC を使って新しいバージョンが MCP Registry に登録されます（シークレットは不要です）。

ロードマップ

• スキャンした文書向けのオプションの OCR 処理
• 取引先名、recargo de equivalencia、EU 域内請求書
• Facturae XML 入力
• 明示的にネットワークを使用するツールとして、オプトイン方式の VIES 検索
• リモート環境へのデプロイ向けのストリーミング可能な HTTP トランスポート

ライセンス

MIT © 2026 Pedro Zapata Medal. サンプル文書はすべて合成データであり、企業名、人物名、納税者番号は架空のものです。