Mexican Tax & Banking

mx-fiscal-mcp-server

AI エージェントにメキシコの税務・銀行関連機能を提供するMCPサーバーです。RFC、CURP、CLABE、NSSを実際のチェックディジットで検証し、CFDI 4.0の請求書を読み取り、SATに有効な状態か問い合わせ、SATのコード表を検索します。APIキー、CSD証明書、PACとの契約は不要です。

Claudeに*「この請求書を読み取って、まだ有効か教えて」*と頼めば、XMLを解析し、SATコードをすべてわかりやすく示し、両方のRFCと計算内容を確認して、SATの公開ステータスサービスに問い合わせます。ウェブツールを3つ開く必要はありません。

> Read this CFDI and check it at the SAT

  parse_cfdi(xml="<cfdi:Comprobante …>")

  CFDI A-1042 — 1160.00 MXN
  ✅ Stamped · version 4.0 · Ingreso
  Emisor:   TES150312DX2 ✅  601 — General de Ley Personas Morales
  Receptor: PELJ900521DK2 ✅  G03 — Gastos en general
  ✅ Totals add up: subtotal − discount + transferred − withheld = total

  cfdi_status(xml="<cfdi:Comprobante …>")

  CFDI status — Vigente
  ✅ The invoice exists in the SAT's records and has not been cancelled.
  Es cancelable: Cancelable con aceptación
  EFOS: returned 200 — the issuer is NOT on the SAT's definitive 69-B list.

---

このプロジェクトの背景

メキシコの電子請求には2つの側面がありますが、ツールが提供されていたのはそのうちの1つだけでした。

CFDIの作成と電子署名には、CSD証明書とPACとの契約が必要です。この側面にはすでにツールがあり、mcp-cfdi-mx （Python）が対応しています。このサーバーは、意図的に競合しないようにしています。

もう1つの側面は読み取りで、必要なものは何もありません。チェックディジットのアルゴリズムは公開されており、SATのカタログも公開されています。印刷された請求書すべてのQRコードのリンク先にある請求書ステータスサービスも、公開されていて認証不要です。それにもかかわらず、RFCの検証を頼まれたエージェントは、XAXX010101000（一般消費者向けに発行されるすべての請求書で使われるRFC）を拒否する正規表現を平気で作り出します。このRFCは独自のチェックディジットを満たさないためです。このサーバーは、読み取りの側面を丁寧に実装したものです。

計算処理はmx-identifiers （MIT、依存関係ゼロ、公開ベクトルを用いた101件のテスト）を使用しています。CFDIリーダーはortamarco.meで稼働しているツールから移植しました。SOAPエンベロープは推測ではなく、nodecfdi/sat-estado-cfdiを参照しました。これは、domain-security-mcp-serverおよびseo-geo-mcp-serverと並ぶ、読み取り専用でキー不要の3つ目のMCPサーバーです。

ツール

識別子

ツール	機能
validate_rfc	個人（13文字）および企業（12文字）のRFCを検証します。完全な剰余11チェックディジット、解析したフィールド、出生日／設立日を返します。SATの汎用RFCを識別し、そのうちどれが計算上の条件を満たすかを示します
validate_curp	18文字のCURPを基数37のチェックディジットで検証します。出生年月日、性別、州（INEGI／ISOではなくRENAPOのキー）、世紀を示す文字を読み取ります
validate_clabe	18桁のCLABEを正しい3-7-1制御ディジットで検証します。重み付けした各積では、各桁の合計（6 + 3 = 9）を使うLuhn方式ではなく、最後の桁のみを数えます（9 × 7 = 63の場合は3）。多くの実装はLuhn方式の合計をそのままコピーしています。Banxicoの銀行コードと支店コードも返します
validate_nss	11桁のIMSS番号をLuhnディジットで検証し、subdelegación／登録年／出生年／シリアル番号に分割します
generate_test_data ⭐	整合性のある架空の個人または企業を1～100件生成します。RFCとCURPは同じ氏名と生年月日から導出され、CLABEには実在の参加銀行を使い、すべてのチェックディジットが有効です

CFDI

ツール	機能
parse_cfdi ⭐	CFDI XML → JSON：ヘッダー、発行者、受領者、移転税と源泉徴収税を含むすべての明細、税額合計、Timbre Fiscal Digital（または null）を取得します。各カタログコードにラベルを付け、両方のRFCを検証し、合計の計算を確認します。ローカル名でドキュメントを走査するため、どのPACの名前空間プレフィックスでも機能します。4.0（Pagos 2.0およびNóminaドキュメントを含みますが、補完情報から抽出されるのはティンブレと地方税のみで、残りは findings に記載されます）と、バージョン警告付きの3.3を読み込みます。Retenciones e información de pagos ドキュメントは、その理由を説明して拒否します
cfdi_status ⭐	SATの公開 ConsultaCFDIService SOAPエンドポイントに問い合わせます。Estado、EsCancelable、EstatusCancelación、ValidaciónEFOSと、それぞれの平易な説明を返します。4つの主要フィールド、またはXML全体を指定できます。失敗時も処理を続行します。タイムアウトは10秒で、タイムアウト、ネットワークエラー、または5xxの後に1回再試行します（4xxの後は再試行しません）。失敗時は available: false を返し、例外は発生しません
cfdi_batch_status	同じサービスを通じて最大25件の請求書を処理します。サービスに負荷をかけない設計です。同時に実行されるリクエストは最大2件で、重複は1回のみ問い合わせ、回答はメモリ内に10分間キャッシュします（サービス停止はキャッシュしません）。失敗が2回連続すると、新たなリクエストを停止します。不正な項目は個別に報告され、リクエストは消費しません

カタログ

ツール	機能
sat_catalog_lookup	9種類の同梱コードテーブル — regimen_fiscal、uso_cfdi、forma_pago、metodo_pago、tipo_comprobante、objeto_imp、impuestos、bancos_clabe、estados_curp — を、コードの完全一致（先頭のゼロは無視）またはアクセントを区別しないテキスト検索で照会します。ネットワークには一切接続しません

すべてのツールは読み取り専用で、outputSchema を宣言し、SDKで検証された structuredContent と、人間が読みやすいMarkdown（デフォルト）またはJSON（response_format="json"）を返します。openWorldHint: true と注釈されているのは cfdi_status と cfdi_batch_status のみです。この2つだけがネットワークに接続します。

リソースとプロンプト

種類	名前	内容
リソース	mx-fiscal://catalogs	9種類の同梱コードテーブルのインデックス
リソース	mx-fiscal://catalog/<name>	1つのテーブル（regimen_fiscal、uso_cfdi、…）をJSONで返します。形式は sat_catalog_lookup と同じです
プロンプト	review_cfdi	請求書を解析し、SATで確認して、両方の結果を正確に報告します
プロンプト	validate_identifiers	RFC／CURP／CLABE／NSSが混在したリストを分類・検証します
プロンプト	seed_test_data	シードファイル用に、有効な架空の個人または企業データを生成します

正直さについての注意事項

これらはここに埋もれているのではなく、ツールの出力に表示されます。

• 構造的に正しいことは、登録済みであることを意味しません。 チェックディジットが合致しても、文字列の形式が正しいことしか示しません。RFC が登録されているかどうかを判断できるのは SAT だけであり、CURP が人物に紐づいているかどうかを判断できるのは RENAPO だけです。このサーバーはどちらにも問い合わせず、そのような問い合わせを行ったと誤解させる表現も使用しません。
• XAXX010101000 は自身のチェックディジットを満たしません。 SAT は一般向け RFC を政令で割り当てましたが、modulus-11 アルゴリズムでは SAT が記載した 0 ではなく 4 が要求されます。XEXX010101000（外国居住者）はチェックディジットを満たします。ツールは両者を「有効」にまとめず、is_generic と check_digit_satisfied を別々のフィールドとして返します。
• CFDI を読み取ることは、検証することではありません。 parse_cfdi は電子署名をチェックしません。完全に解析できる請求書でも、取り消されている場合や、丸ごと偽造されている場合があります。
• SAT に到達できなくても、請求書が無効だとは限りません。 ステータスエンドポイントは SLA もステータスページも公開しておらず、停止することもあります。そのドキュメントには、1 時間あたり最大 200 万件のクエリに対応できると記載されており、クエリごとに SAT のトランザクションデータベースを読み取るため、クエリ数を増やさないよう呼び出し元に求めています。cfdi_status は理由とともに available: false を返します。これは SAT についての説明であり、ドキュメントについての説明ではありません。
• 銀行リストは一部のみです。 bancos_clabe には Banxico の主要な参加銀行が含まれており、全カタログではありません。未知のコードは、架空の名称を付けずに未知として報告されます。プラサのカタログは一切同梱されていないため、プラサコードはそのまま返されます。
• EFOS コードは SAT 独自の表から読み取ります。 SAT は Documentación del Servicio de Consulta de CFDI v1.4 のセクション 3 で ValidacionEFOS を説明しています。100、101、104 は発行者が 69-B の確定リストに掲載されていることを示します。102 と 103 は、発行者は掲載されていないものの、請求書の発行対象となった第三者の RFC（a cuenta de terceros）が掲載されていることを示します。200 と 201 は発行者が掲載されていないことを示します（201 は第三者も掲載されていません）。efos_state が示すのは発行者のみで、efos_third_party_state（listed／not_listed／not_reported／unknown）が第三者の状態を示します。フィールドが空の場合や未文書化のコードの場合は、validacion_efos に生のコードを保持したまま unknown として報告し、「掲載済み」とはしません。バージョン 1.0.1 以前では 102 と 103 を発行者がリストに掲載されているものとして報告していましたが、1.0.2 で修正されています。
• Bineo の CLABE（銀行コード 165）。 1.0.3 では、これらの修正を含む mx-identifiers ^1.0.1 が必要です。

プロトコル

v2 MCP SDK を基盤としているため、2026-07-28 リビジョン（server/discover、initialize なし、リクエストごとの _meta エンベロープ）に対応し、同じサーバーファクトリーから Claude Desktop、Claude Code、Cursor などの 2025 年代のクライアントにも引き続き対応します。エントリーポイントが時代の判定を担います。stdio では serveStdio(factory)、HTTP ではデフォルトの legacy: 'stateless' を指定した createMcpHandler(factory) を使用します。セッション状態はなく、どちらの方向にも Mcp-Session-Id はありません。npm run smoke は両方の世代で各ツールを実行し、各接続でネゴシエートされた世代を検証します。

ツールリストはコンパイル時定数であるため、2026 年世代の接続では tools/list と server/discover が、SDK の保守的な ttlMs: 0 ではなく、cacheScope: 'public' を指定した実際の 1 時間の ttlMs を通知します。

インストール

Node.js 20+ が必要です。クローンは不要です。どの MCP クライアントからも npx で実行できます。

Claude Code での使用

claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server

-- の前に --scope user（すべてのプロジェクト）または --scope project（共有の .mcp.json を書き込みます）を追加してください。デフォルトでは現在のプロジェクトにのみ適用されます。

Claude Desktop で使用する

設定 → 開発者 → 設定を編集を開き、claude_desktop_config.json に追加します — examples/ を参照してください：

{
  "mcpServers": {
    "mx-fiscal": {
      "command": "npx",
      "args": ["-y", "mx-fiscal-mcp-server"]
    }
  }
}

Windows では、"command": "cmd" と "args": ["/c", "npx", "-y", "mx-fiscal-mcp-server"] を使用します。 クライアントを再起動してから、次のように尋ねます：「シードファイル用に、有効な RFC と CURP を持つメキシコの顧客を 10 人生成してください。」

Cursor で使用する

同じ JSON ブロックを ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（このプロジェクトのみ）に記述します。

Codex で使用する

codex mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server

または ~/.codex/config.toml に記述します（プロジェクトスコープの .codex/config.toml も使用できます）：

[mcp_servers.mx-fiscal]
command = "npx"
args = ["-y", "mx-fiscal-mcp-server"]

セルフホスト（HTTP トランスポート）

同じサーバーが、リモートまたは複数クライアントでの使用向けに、ステートレスな Streamable HTTP に対応しています。

TRANSPORT=http npx -y mx-fiscal-mcp-server
# POST JSON-RPC to http://127.0.0.1:3000/mcp   ·   health at /healthz

デフォルトで安全です。127.0.0.1 にバインドされ、localhost の Host ヘッダーと Origin ヘッダーのみを受け付けるため、Web ページを利用した DNS リバインディング攻撃をブロックします。 Coolify や Traefik の背後などで公開するには、明示的に有効にしてください：

変数	デフォルト	用途
TRANSPORT	stdio	Streamable HTTP で提供する場合は http
PORT	3000	リッスンポート。1～65535 以外の場合、サーバーは 1 行のメッセージを出して停止します
HOST	127.0.0.1	バインドアドレス。リモート接続を受け付ける場合は 0.0.0.0
ALLOWED_HOSTS	—	Host ヘッダーに指定できる、カンマ区切りのホスト名（例：mcp.example.com）
ALLOWED_ORIGINS	—	ブラウザーからの呼び出しを許可する、カンマ区切りのオリジン
MCP_AUTH_TOKEN	—	設定した場合、すべてのリクエストで Authorization: Bearer <token> が必要です
MAX_XML_CHARS	2000000	受け付ける CFDI の最大文字数
MAX_CONCURRENT_CFDI	4	一度に処理する parse_cfdi / cfdi_status / cfdi_batch_status の呼び出し数。残りには再試行を促すメッセージが返されます

CORS ヘッダーは一切送信されないため、Web ページはクロスオリジンでレスポンスを読み取れません。ALLOWED_ORIGINS は、ハンドラーへの通過を許可する Origin ヘッダーのみを決定します（MCP クライアントのようにヘッダーがないリクエストは常に通過します）。リクエスト本文のサイズ上限は、MAX_XML_CHARS の約 1.25 倍です。

セルフホストのインスタンスは、呼び出し元に代わって SAT にリクエストを送信するため、MCP_AUTH_TOKEN なしで公開しないでください。認証なしで公開すると、IP アドレスがレート制限される原因になり得る無料の中継サーバーになります。Docker を使用する場合（イメージでは HOST=0.0.0.0 が設定されています）：

docker build -t mx-fiscal-mcp .
docker run -p 3000:3000 -e ALLOWED_HOSTS=mcp.example.com -e MCP_AUTH_TOKEN=change-me mx-fiscal-mcp

開発

npm run dev        # tsx watch (stdio)
npm run typecheck  # tsc --noEmit
npm test           # deterministic offline unit tests, HTTP transport defaults included
npm run smoke      # every tool over the real protocol, on BOTH eras (queries the SAT)
node scripts/smoke-all.mjs --offline   # the same, minus the calls that reach the SAT
npm run inspect    # MCP Inspector against the built server
npm run build      # type-check + emit dist/

動作の仕組み

src/
├── index.ts        # transport selection: serveStdio | createMcpHandler + Express
├── server.ts       # the server FACTORY — registers every tool, holds the instructions
├── schemas.ts      # Zod 4 outputSchema for each tool
├── constants.ts    # the single external host, timeouts, limits
├── format.ts       # markdown/JSON response shaping, findings
├── core/           # pure logic, no MCP coupling — reusable & testable
│   ├── identifiers.ts # reporting layer over mx-identifiers (errors, labels, findings)
│   ├── cfdi.ts        # the CFDI 4.0 reader, ported 1:1 from the web tool
│   ├── sat.ts         # SOAP envelope, expression builder, response interpretation
│   ├── catalogs.ts    # the nine code tables + lookup
│   └── testdata.ts    # fixture generation
└── tools/          # thin MCP wrappers (Zod schemas, descriptions, formatting)

core/ レイヤーには MCP の型が含まれていないため、同じロジックをこのサーバーと Web UI の両方で使用できます。チェックディジットの計算はすべて mx-identifiers にあり、ここでは再実装していません。

ネットワークの接続先： 接続先ホストは constants.ts にハードコードされた consultaqr.facturaelectronica.sat.gob.mx の 1 つだけです。呼び出し元から URL を受け取るツールはないため、SSRF の対策は不要です。ほかの 7 つのツールはネットワーク呼び出しを一切行いません。

信頼できない XML： DOCTYPE を宣言するドキュメントは、解析前に拒否されます（CFDI に DOCTYPE はありません）。また、サイズと要素数の上限により、1 回の解析で使用できるメモリを制限しています。結果内の属性値は 4,000 文字で切り詰められます。cfdi_status は、リクエストを送信する前に RFC、合計金額、UUID を検査します。問題を見つけた場合は、非公開のセキュリティアドバイザリを作成してください。

---

スペイン語

AI エージェントに、誰もが何度も誤って再実装しているメキシコの税務機能を提供する MCP サーバーです。実際のチェックディジットを使った RFC、CURP、CLABE、NSS の検証、XML 形式の CFDI 4.0 の読み取り、SAT でのステータス照会、SAT の カタログ検索ができます。API キーも CSD も PAC も不要です。

これは「読み取り」機能の半分です。 CFDI の作成と封印にはデジタルシール証明書と PAC が必要で、その機能はすでに mcp-cfdi-mx（Python）が提供しています。このサーバーはそれと競合するのではなく、補完します。

このサーバーが適切に処理でき、ほとんど誰もできていないこと：

• XAXX010101000 は、自身のチェックディジットを満たしません。 SAT が政令によって割り当てた値ですが、モジュール 11 では SAT が設定した 0 ではなく 4 が必要です。XEXX010101000（国外居住者）はチェックディジットを満たします。そのため、多くのフォームで一般消費者向けの請求書が拒否されます。ツールは is_generic と check_digit_satisfied を個別に返します。
• CLABE のチェックディジットには、3-7-1 の重み付けをした各積の最後の桁を使います。各積の桁の合計ではありません。 9 × 7 = 63 なら数えるのは 3 です。Luhn の方式をそのまま使う実装は 6 + 3 = 9 と合計し、別のディジットを算出します。基数 09000000000000000 の場合、アルゴリズムでは 7、Luhn 方式では 1 になります。合計の前後どちらで 10 を法とする剰余を求めても結果は同じで、誤りはそこではありません。
• CURP の州コードは、INEGI や ISO 3166-2:MX ではなく RENAPO によるものです。 DF はメキシコシティ、MC はメキシコ州、NE は国外出生を表します。
• SAT のサービスは停止することがあり、SLA も公表していません。 ドキュメントでは、1 時間あたり最大 200 万件の照会に対応できるとし、照会はすべてトランザクションデータベースにアクセスするため、照会件数を増やさないよう求めています。cfdi_status は理由とともに available: false を返す形で機能を縮退させます。例外を送出することはなく、SAT の障害を「請求書が無効」と解釈してはいけません。
• 構造上の有効性は、登録済みであることを意味しません。 チェックディジットが一致するのは、文字列の形式が正しいことを示すだけです。

何もクローンせずにインストールできます：claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server。

演算エンジンには mx-identifiers（MIT、依存関係ゼロ）を使用しています。CFDI リーダーは ortamarco.me で稼働しているツールのものです。SOAP エンベロープは、独自に考案したものではなく、nodecfdi/sat-estado-cfdi のコードを参考にしています。

このサーバーはプロトコルの 2026-07-28 版に対応しており、同じサーバーファクトリーから、2025 年のクライアント（Claude Desktop、Claude Code、Cursor）にも引き続き対応します。

ライセンス

MIT © Marco Orta