Facture Électronique France

mcp-facture-electronique-fr 🇫🇷

英語 | フランス語

フランスの電子請求書改革（2026年9月1日施行）向けに、標準化された AFNOR XP Z12-013 API を公開する Python MCP サーバーです。このプロジェクトにより、AI エージェント（Claude、IDE）が互換ソリューション（SC）として、認定プラットフォーム（PA/PDP）エコシステムとネイティブに連携できます。

---

はじめに

このパッケージは、欧州の電子請求書 MCP サーバー向け共通基盤ライブラリである mcp-einvoicing-core を基盤としています。このライブラリは、このパッケージで使用する OAuth2 HTTP クライアント、トークンキャッシュ、共通モデル、ログユーティリティ、例外階層を提供します。

mcp-einvoicing-core は推移的依存関係として自動的にインストールされるため、追加の手順は不要です。

貢献者向け： pip install -e ".[dev]" を実行すると、ベースパッケージが PyPI から自動的にインストールされます。

このサーバーは、フランスの電子請求書改革で定義されている**互換ソリューション（CS）**モードで動作します。CS は、企業の情報システムと認定プラットフォーム（AP/PDP）の間の仲介役となります。つまり、次のとおりです。

• 呼び出し元から渡されたペイロードのプロファイル検証は行いません。 サーバーは、請求書ファイル（Factur-X PDF/A-3、UBL 2.1、または CII XML）を渡されたまま送信します。構造検証とビジネスルール検証（NF XP Z12-012 プロファイル、Schematron ルール）は、このサーバーではなく、受信側の認定プラットフォームが実施します。
• スキーマレベルの XSD を超える e-reporting ペイロードの検証は行いません。 取引レポート（Flux 10.1/10.3）と支払レポート（Flux 10.2/10.4）は、validate_ereporting_xml の呼び出し時に DGFiP v3.2 XSD スキーマに照らして検証されますが、より詳細なビジネスルールのチェック（たとえば、申告額と請求書合計額の整合性）は AP の責任です。
• PDF/A-3 エンベロープの生成は行いません。 呼び出し元は、CII XML を埋め込んだ適合済みの Factur-X PDF/A-3 ファイルを作成する必要があります。このサーバーは完成したバイナリを送信します。

認定プラットフォームが最終検証を行い、適合しない送信をエラーコードとメッセージとともに拒否する場合があります。

インストール

PyPI 経由（推奨）

pip install mcp-facture-electronique-fr

または、事前にインストールせずに uvx を使用する場合：

uvx mcp-facture-electronique-fr

Factur-X Schematron 検証（validate_facturx。XSLT 2.0 / Saxon-HE バックエンドが必要です。以下の「利用可能なツール」の FR-XSLT2-1 を参照）：

pip install mcp-facture-electronique-fr[xslt2]

ソースから

# Clone the repository
git clone https://github.com/cmendezs/mcp-facture-electronique-fr.git
cd mcp-facture-electronique-fr

# Create the virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e ".[dev]"

# Initial configuration
cp .env.example .env
# Edit .env with the credentials provided by your PA/PDP

設定（.env）

認定プラットフォーム（PA）で認証するには、サーバーに次の変数が必要です。

変数	説明
PA_BASE_URL_FLOW	PA Flow Service のベース URL
PA_BASE_URL_DIRECTORY	非推奨 — 現在は読み取られません。PPF_ANNUAIRE_BASE_URL を参照してください
PPF_ANNUAIRE_BASE_URL	PPF Annuaire サービスのベース URL（デフォルトは本番用 swagger の servers URL。サンドボックステスト用に上書きできます）
PA_CLIENT_ID	OAuth2 クライアント ID
PA_CLIENT_SECRET	OAuth2 クライアントシークレット
PA_TOKEN_URL	認証サーバーの URL
PA_ORGANIZATION_ID	マルチテナント AP の組織識別子（任意）
HTTP_TIMEOUT	リクエストのタイムアウト（デフォルト：30s）
PPF_GLOBAL_ID	CDAR の 2 つ目の RecipientTradeParty に使用する PPF party GlobalID（任意。デフォルトでは未設定。「submit_lifecycle_status」を参照）
PPF_SCHEME_ID	PPF_GLOBAL_ID の schemeID（デフォルト 0238）
PPF_NAME	PPF RecipientTradeParty の名前（デフォルト PPF）
PPF_ROLE_CODE	PPF RecipientTradeParty の RoleCode（デフォルト DFH）

Claude Desktop との連携

このサーバーを Claude で使用するには、次の設定を claude_desktop_config.json ファイルに追加します。

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      }
    }
  }
}

Cursor との連携

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

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

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      }
    }
  }
}

変更を適用するには、Cursor ウィンドウを再読み込みします（Ctrl+Shift+P を押してから ウィンドウの再読み込み）。

Kiro との連携

Kiro は専用の設定ファイルで MCP サーバーをサポートしています。次の 2 つの設定レベルがあります。

• グローバル（すべてのプロジェクト）：~/.kiro/settings/mcp.json
• ワークスペース（このリポジトリのみ）：.kiro/settings/mcp.json

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

ファイルは保存時に自動的に再読み込みされます。コマンドパレットから設定を開くこともできます（Cmd+Shift+P / Ctrl+Shift+P を押してから MCP）。

Kiro のセキュリティに関するヒント：シークレットを平文で記述する代わりに、"PA_CLIENT_SECRET": "${PA_CLIENT_SECRET}" の構文を使用します。Kiro は起動時にシェル環境変数を解決します。

利用可能なツール

サービス	ドメイン	標準	MCP ツール
Flow Service	請求書フローおよび電子報告	Annex A, v1.2.0	5 ツール
PPF Annuaire（ディレクトリ）	中央ディレクトリ（SIREN/SIRET/ルーティング/アドレス指定）	PPF swagger v1.11.0	20 ツール
Webhook Service	イベント通知サブスクリプション	Annex A, v1.2.0	5 ツール
Factur-X Service	CII XML 検証（Schematron）	Factur-X 1.09.2	1 ツール

テキストは 2026 年 6 月版に更新済み（swagger は現行の v1.2.0）— AFNOR は 2026 年 6 月に、swagger を更新せずに XP Z12-013 の説明テキストを再提供しました。サーバーは引き続き v1.2.0 のワイヤー契約を実装しています。

注記（FR-XSLT2-1、解決済み）： 同梱の Factur-X 1.09.2 Schematron スタイルシートには XSLT 2.0 が必要ですが、lxml/libxslt（XSLT 1.0 のみ）ではコンパイルできません。これは ZUGFeRD で追跡されている DE-XSLT2-1 の問題と同じ根本原因です。 validate_facturx は現在、Saxon-HE を使用して実際の Schematron 検証を実行します。 これを機能させるには、オプションの xslt2 エクストラをインストールしてください。 pip install mcp-facture-electronique-fr[xslt2]。インストールしない場合、ツールは level="unavailable" に正常にフォールバックします。

注記（FR-FLUX11-2026-06、PPF Annuaire）： ディレクトリツールは、同梱の PPF-platform swagger ppf-openapi-annuaire-api-public-1.11.0-openapi.json に直接接続されています。これは PPF-platform 固有のインターフェースであり、PDP に依存しない Annex B の抽象化ではありません。 swagger 自身の説明によると、これらのエンドポイントは変更される可能性があり、 使用前に PISTE アプリケーションを公開しておく必要があります。

Flow Service（フロー管理）

• submit_flow：請求書（Factur-X、UBL、CII）または電子報告データを送信します。
• search_flows：標準フィルターを使用して、送信済みまたは受信済みのフローを複数の条件で検索します。
• submit_lifecycle_status：ライフサイクルのステータス（例：利用可能、収集済み、異議あり）を更新します。
• get_flow：特定のフローの詳細と添付ファイルをすべて取得します。
• healthcheck_flow：PA Flow API の接続性と可用性をテストします。

PPF Annuaire（ディレクトリ）

同梱されている PPF-platform swagger ppf-openapi-annuaire-api-public-1.11.0-openapi.json を直接使用しています。上記の注記をご覧ください。

• search_company / get_company_by_siren / get_company_by_id_instance：法人単位（SIREN）を検索します。
• search_establishment / get_establishment_by_siret / get_establishment_by_id_instance：事業所（SIRET）を検索します。
• search_routing_code / get_routing_code_by_siret_and_code / get_routing_code_by_id_instance / create_routing_code / update_routing_code / replace_routing_code：ルーティングコード（code-routage）を管理します。
• search_directory_line / get_directory_line_by_code / get_directory_line / create_directory_line / update_directory_line / replace_directory_line / delete_directory_line：電子請求書の受信アドレスであるディレクトリ行（ligne-annuaire）を管理します。
• check_ppf_annuaire_health：PPF Annuaire サービスの可用性を確認します。

Webhook Service（Webhook 管理）

• list_webhooks：現在のトークン所有者のすべての Webhook サブスクリプション ID を一覧表示します。
• get_webhook：Webhook サブスクリプションの詳細を取得します。
• create_webhook：フローイベント通知を購読します（フローの種類、方向、処理ルールで絞り込みます）。
• update_webhook：Webhook の技術パラメーター（認証、署名）を更新します。
• delete_webhook：Webhook の購読を解除します。

アーキテクチャ

このサーバーは、AI エージェントと改革の技術インフラストラクチャーをつなぐ、インテリジェントな通信インターフェースとして機能します。

[ ERP / Business IS ] <--> [ MCP Server ] <--> [ Approved Platform (PA/PDP) ]
          ^                        |
          |                        v
   [ AI Agent (Claude) ] <--- (XP Z12-013 Standard)

ベンダー中立性

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

法律上、PDP（Plateforme de Dématérialisation Partenaire）が必要ですが、その API は XP Z12-013 に基づいて標準化されているため、プロバイダーの切り替えはコード変更ではなく、設定変更で済みます。

対応規格

• AFNOR XP Z12-012：請求書メッセージ形式、プロファイル、ライフサイクル状態（2026年6月版 v1.4）。
• AFNOR XP Z12-013：サービスインターフェース仕様（2026年6月版、v1.2.0 ワイヤー契約）。
• AFNOR XP Z12-014：ビジネスユースケース向け技術実装ガイド（2026年6月版 v1.4）。
• フランスの B2B 改革：義務化の導入スケジュール（2024～2026年）。

テスト

# Run the unit and integration test suite
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 をご覧ください。