mcp-cfdi-mx

mcp-cfdi-mx 🇲🇽

English | Español

SATのAnexo 20技術標準に準拠した、メキシコの電子インボイス（CFDI 4.0およびComplemento de Pagos 2.0）向けツールを提供するPython製MCP サーバーです。AI エージェント（Claude、IDE）がCFDI 4.0文書（Ingreso、Egreso、Complemento de Pagos 2.0）を作成し、XSD検証して封印するほか、PACから返されたTimbre Fiscal Digitalスタンプを検証し、メキシコのRFC納税者番号を検証できます。

フェーズ1の対象範囲。 このパッケージが対応するのはCFDI 4.0のIngreso、Egreso、およびComplemento de Pagos 2.0のみです。Carta Porte、Complemento de Nómina、Retenciones、Comercio Exteriorにはまだ対応しておらず、PACへの送信も行いません。現在実装されている機能の詳細は利用可能なツールをご覧ください。

---

はじめに

このパッケージは、電子インボイス向けMCP サーバーの共有基盤ライブラリであるmcp-einvoicing-coreを基盤としています。InvoiceDocumentモデルの基底クラス、TaxIdentifier.validate_mx_rfc RFCバリデーター、およびSelloDigitalSignerを提供します。SelloDigitalSignerは、coreの文書署名抽象化をMX向けに具体的に実装したもので、SATのAnexo 20に従い、cadena originalのSHA-256ダイジェストをemisorのCSDでRSA-PKCS#1v1.5署名します。

mcp-einvoicing-coreは依存関係として自動的にインストールされるため、追加の手順は必要ありません。

CFDIはクリアランスモデルの標準です。CFDIが法的に有効となるのは、PAC（Proveedor Autorizado de Certificación）が認証し、Timbre Fiscal Digital（TFD）を返した後に限られます。このパッケージはPACへの送信を行わず、PACに依存しません。sealing_modeパラメーターで選択することで、ローカルで封印されたCFDI（封印済み文書を受け付ける任意のPACに渡せる状態）または未封印のスキーマ準拠CFDI（emisorに代わってPACが封印する場合向け）のいずれかを生成します。

インストール

PyPI経由（推奨）

pip install mcp-cfdi-mx

事前にインストールせず、uvxを使う場合：

uvx mcp-cfdi-mx

ソースから

git clone https://github.com/cmendezs/mcp-cfdi-mx.git
cd mcp-cfdi-mx
uv sync --all-extras

設定（環境変数）

このパッケージに必須の環境変数はありません。CSD証明書／鍵のパスとパスワードはツールの引数として渡します（ファイルパスまたは環境変数参照を使用し、リクエストに鍵の情報を平文で埋め込まないでください）。固定の環境変数名から読み込むことはありません。

Claude Desktopとの連携

claude_desktop_config.jsonファイルに次の設定を追加します。

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

Cursorとの連携

Cursorはstdio経由でMCP サーバーに対応しています。次の場所に設定を追加します。

• グローバル（すべてのプロジェクト）：~/.cursor/mcp.json
• プロジェクトごと（このリポジトリのみ）：.cursor/mcp.json

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

変更を保存した後、Cursorのウィンドウを再読み込みします（Ctrl+Shift+P → ウィンドウの再読み込み）。

Kiroとの連携

Kiroは専用の設定ファイルを使用してMCP サーバーに対応しています。

• グローバル：~/.kiro/settings/mcp.json
• ワークスペース：.kiro/settings/mcp.json

{
  "mcpServers": {
    "cfdi-mx": {
      "command": "uvx",
      "args": ["mcp-cfdi-mx"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

セキュリティに関するヒント：今後のツールバージョンで環境変数参照による認証情報の受け渡しに対応した場合は、"VAR_NAME": "${VAR_NAME}"という構文を使用してください。Kiroが認証情報を平文で保存するのではなく、シェルから解決します。

利用可能なツール

作成

ツール	説明
mx__build_cfdi	構造化された入力から、整形式で未封印のCFDI 4.0 Comprobante XML（IngresoまたはEgreso）を作成します
mx__build_pago	Complemento de Pagos 2.0 CFDI（TipoDeComprobante="P"）を作成します。SATのガイドで指定されている固定の単一Conceptoラッパーを組み立てます

検証と封印

ツール	説明
mx__validate_cfdi	cfdv40.xsd に対する完全な XSD 検証を行います。補足情報が含まれている場合は、TimbreFiscalDigitalv11.xsd.xml および／または Pagos20.xsd.xml も検証します
mx__seal_cfdi	SelloDigitalSigner を介してデジタルシールを計算します。sealing_mode（"local" | "pac"）に対応しています
mx__verify_tfd	PAC から返された Timbre Fiscal Digital 1.1 スタンプを解析し、PAC の証明書が指定されている場合は SelloSAT を暗号学的に検証します

対応範囲

ツール	説明
mx__get_supported_scope	このパッケージが現在サポートしている CFDI 文書の種類、補足情報、およびシール方式を返します

各ツールのパラメーターの詳細については、稼働中のツールレジストリから生成された docs/TOOLS.md を参照してください。

未実装

PAC への送信処理（このパッケージは特定の PAC に依存せず、特定の PAC に送信しません）、および後続フェーズの補足情報（Carta Porte、Complemento de Nómina、Retenciones、Comercio Exterior）。

アーキテクチャ

mcp_cfdi_mx.models.CFDIComprobante は mcp_einvoicing_core.models.InvoiceDocument を拡張しています（EN 16931 に準拠しない経路です。CFDI は CEN TC 434 より前に制定され、同規格に由来するものではありません。これは mcp-nfe-br と同じ判断です）。Emisor と Receptor の RFC 検証は、どちらも TaxIdentifier.validate_mx_rfc（core）を経由します。シール処理は mcp_einvoicing_core.digital_signature.SelloDigitalSigner を経由します。これは core の BaseDocumentSigner を MX 向けに具体化したもので、ES（XAdES）、BR（XML-DSig）、IT（CAdES）でも各国の署名規格に同じパターンが使用されています。

[ ERP System / Application ] <--> [ MCP Server ] <--> [ PAC (any, PAC-agnostic) / SAT ]
          ^                           |
          |                           v
   [ AI Agent (Claude) ] <--- (CFDI 4.0 / Pagos 2.0)

ベンダー中立性

このサーバーは標準自体を実装しており、文書をローカルで作成、検証、署名します。商用の請求プラットフォーム向けクライアントではなく、署名キーや認証情報が自社のインフラストラクチャから外に出ることはありません。

PAC（Proveedor Autorizado de Certificación）は CFDI にスタンプを付与する必要があります。このサーバーは独自の CSD を使用してローカルで封印し、すでに封印された文書を PAC に渡します。

対応規格

規格	バージョン	出典
CFDI (Comprobante Fiscal Digital por Internet)	4.0	SAT Anexo 20, DOF 2022-01-13
Timbre Fiscal Digital	1.1	SAT
Complemento de Pagos	2.0	SAT

ソース一式と取得日については、specs/README.md を参照してください。

テスト

uv run pytest tests/ -v

コントリビューション

コントリビューションを歓迎します。ガイドラインについては CONTRIBUTING.md を参照してください。

その他の電子請求 MCP サーバー

国	サーバー
🌍 グローバル	mcp-einvoicing-core
🇧🇪 ベルギー	mcp-einvoicing-be
🇧🇷 ブラジル	mcp-nfe-br
🇫🇷 フランス	mcp-facture-electronique-fr
🇩🇪 ドイツ	mcp-einvoicing-de
🇮🇳 インド	mcp-einvoicing-in
🇮🇹 イタリア	mcp-fattura-elettronica-it
🇲🇽 メキシコ	mcp-cfdi-mx
🇵🇱 ポーランド	mcp-ksef-pl
🇸🇬 シンガポール	mcp-invoicenow-sg
🇪🇸 スペイン	mcp-facturacion-electronica-es
🇦🇪 アラブ首長国連邦	mcp-einvoicing-ae

ライセンス

このプロジェクトは Apache 2.0 ライセンスで配布されています。 詳細については LICENSE ファイルを参照してください。完全なバージョン履歴については CHANGELOG.md を参照してください。