mcp-einvoicing-de

mcp-einvoicing-de 🇩🇪

English | Deutsch

ZUGFeRD 2.x および XRechnung 3.x 形式（EN 16931、FeRD、KoSIT）によるドイツの電子請求書に対応した、Python 製の MCP（Model Context Protocol）サーバーです。AI エージェント（Claude、IDE）が、ドイツの B2B 電子請求書義務（2025 年から適用され、2027 年から 2028 年にかけて段階的に施行）および欧州規格 EN 16931 に完全準拠した電子請求書を作成、検証、解析、変換できます。

---

はじめに

このパッケージは、欧州の電子請求書 MCP サーバー向けの共有基盤ライブラリである mcp-einvoicing-core を基盤としています。共有モデル、検証の抽象化、XML ユーティリティ、例外階層を提供します。

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

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

インストール

PyPI 経由（推奨）

pip install mcp-einvoicing-de

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

uvx mcp-einvoicing-de

ソースから

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

オプションの追加機能

追加機能	目的	インストール
[xslt2]	XSLT 2.0 Schematron スタイルシート（FeRD Factur-X 1.09.2 および KoSIT XRechnung 3.0.2）向けの Saxon-HE バックエンドです。ローカルでの Schematron 検証に必要です。lxml が対応するのは XSLT 1.0 のみです。	pip install mcp-einvoicing-de[xslt2]
[pdf]	埋め込み XML の抽出に使用する追加の PDF ユーティリティです（PDF/A-3 生成には pikepdf も基本依存関係として必要です）。	pip install mcp-einvoicing-de[pdf]
[pymupdf]	代替 PDF エンジンです（PyMuPDF を使用します）。	pip install mcp-einvoicing-de[pymupdf]
[dev]	開発ツール（pytest、ruff、pre-commit）です。	pip install mcp-einvoicing-de[dev]

設定

このサーバーは外部認証情報を必要としません。使用できる環境変数：

変数	説明	デフォルト
EINVOICING_DE_LOG_LEVEL	ログレベル（DEBUG、INFO、WARNING、ERROR）	INFO
EINVOICING_DE_KOSIT_VALIDATOR_URL	セルフホスト可能な KoSIT 検証ツールの REST エンドポイント URL です。クラウド検証が有効な場合にのみ使用されます。EINVOICING_DE_KOSIT_ENABLE を参照してください
EINVOICING_DE_KOSIT_ENABLE	1 に設定すると、KoSIT クラウド検証（validator.kosit.de またはセルフホスト可能なエンドポイント）が有効になります。デフォルトではローカルの Schematron のみで検証します
EINVOICING_PEPPOL_CODELIST_DIR	Peppol コードリストツールに必要な、OpenPeppol eDEC Code Lists の独自コピーを含むローカルディレクトリです（このパッケージには同梱されていません。mcp-einvoicing-core の README を参照してください）
EINVOICING_EN16931_CODELIST_DIR	EN 16931 コードリストツールに必要な、CEF「Digital Building Blocks」EN 16931 semantic code lists の独自コピーを含むローカルディレクトリです（同梱されていません。mcp-einvoicing-core の README を参照してください）

EUSR/TSR レポート作成ツールおよび MLS ツールで Schematron 検証を行うには、[xslt2] 追加機能も必要です。

Claude Desktop との連携

claude_desktop_config.json に次のエントリを追加してください。環境変数は不要です：

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

Cursor との連携

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

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

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

変更を適用するには、Cursor ウィンドウを再読み込みしてください（Ctrl+Shift+P を押してから Reload Window を選択します）。

Kiro との連携

Kiro は、専用の設定ファイルを使用して MCP サーバーに対応しています。次の 2 つの設定レベルを利用できます。

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

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

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

利用可能なツール

ツール	説明
invoice_create	ZUGFeRD または XRechnung の XML（CII または UBL）を生成します。§14 Abs. 2 UStG の B2B 義務を適用します。DE で始まる VAT 購入者に対しては、transitional_period_opt_in=True が設定されていない限り、XML 以外の出力は拒否されます。output_format='pdf' を指定すると、sRGB ICC プロファイル、OutputIntent、埋め込みフォント、決定論的な /ID を備えた PDF/A-3 レベル B のハイブリッド請求書が生成されます。
invoice_validate	EN 16931 および KoSIT のルール（BR-DE-*）に照らして請求書を検証します。ローカルの Schematron 検証がデフォルトで実行されます（データはマシンの外部に送信されません）。KoSIT クラウド検証（validator.kosit.de またはセルフホストのエンドポイント）を利用するには、cloud_validate=True または EINVOICING_DE_KOSIT_ENABLE=1 を設定します。指数バックオフによる再試行（1s/2s/4s）が行われます。XSLT 2.0 のローカル検証には [xslt2] extra が必要です。
invoice_parse	ZUGFeRD または XRechnung の XML、あるいは factur-x.xml / zugferd-invoice.xml が埋め込まれた PDF/A-3 ハイブリッド請求書から、構造化データを抽出します。
invoice_convert	ZUGFeRD プロファイル間の変換、ZUGFeRD/XRechnung CII ヘッダーの入れ替え、またはコアの convert_wire_format による構文間の CII/UBL 変換を行います。
datev_export	ZUGFeRD 請求書を、DATEV の会計ソフトウェアにインポートするための DATEV EXTF 700 Buchungsstapel CSV ファイルとしてエクスポートします。デフォルトでは SKR 03 の勘定科目（収益 8400／売掛金 10000）を使用します。
tax_rules	ドイツの VAT ルール（税率、§13b UStG のリバースチャージコード、JStG 2024 の基準額である前年度 €25,000／当年度 €100,000 の §19 UStG Kleinunternehmer しきい値、免税）を照会します。

Peppol ネットワークツール

Peppol 参加者の検索、サービスエンドポイントの検索、DNS のみの診断、AS4 送信、Peppol Directory 検索、OpenPeppol eDEC コードリストツールは、共有コア Peppol ツールプラグイン（mcp_einvoicing_core.peppol.tools.register_peppol_tools）によって提供され、ドイツ固有の識別子アダプターとともに server.py にマウントされます。USt-IdNr（例：123456789 または DE123456789）のみの場合は、Peppol スキーム 9930:<value>（DE:VAT）に正規化されます。すでにスキームが付与された識別子（例：9930:DE123456789、または Leitweg-ID でルーティングされる B2G 請求書の 0204:<leitweg-id>）は変更されずに渡されます。AS4 で送信するには、まず invoice_convert（または target_syntax='UBL' を指定した invoice_create）で XRechnung UBL を生成し、その結果を peppol_send に渡します。

peppol_send は、mcp-einvoicing-core v1.20.0 以降、送信メッセージに実際の wsse:Security 署名を付与します（以前は計算した署名を破棄していました。CHANGELOG.md v0.10.0 を参照）。

ツール	説明
peppol_lookup_participant	事業者が Peppol ネットワークに登録されているか確認し、登録状況と対応するドキュメントタイプを返します
peppol_get_service_endpoint	参加者のドキュメントタイプに対応する AS4 エンドポイントを取得します
resolve_peppol_dns	SMP の到達可否に依存しない、DNS のみ（SML）の診断
peppol_send	AS4 経由で UBL/CII 請求書を送信します
peppol_directory_search	参加者、名前、国、またはドキュメントタイプで公開 Peppol Directory を検索します
list_participant_id_schemes, list_document_type_ids, list_process_ids, list_spis_use_case_ids	OpenPeppol eDEC コードリストの照会（EINVOICING_PEPPOL_CODELIST_DIR が必要です）
check_document_type_id_in_codelist, check_process_id_in_codelist, check_participant_id_scheme_in_codelist, get_peppol_codelist_version	OpenPeppol eDEC コードリストのチェックとバージョンの報告

これらのツールのパラメーターに関する詳しいドキュメントは、mcp-einvoicing-core README を参照してください。

Peppol のレポートおよびステータスツール

v0.10.0 で、オプトイン方式の 3 つのコアプラグインを通じて追加されました。server.py で無条件にマウントされます。いずれも、追加機能またはデータディレクトリが見つからない場合、登録時ではなく呼び出し時に明確なエラーを返します。

ツール	プラグイン	説明
validate_eusr_report	register_peppol_reporting_tools	エンドユーザー統計レポート（XSD、その後 Schematron）を検証します。[xslt2] エクストラが必要です。
validate_tsr_report	register_peppol_reporting_tools	トランザクション統計レポート（XSD、その後 Schematron）を検証します。[xslt2] エクストラが必要です。
validate_mls_message	register_peppol_mls_tools	メッセージレベルステータス文書（UBL ApplicationResponse-2 サブセット）を検証します。[xslt2] エクストラが必要です。
build_mls_message	register_peppol_mls_tools	文書レベルの MLS 応答を作成します。[xslt2] エクストラが必要です。
13 組の list_*／check_* と get_en16931_codelist_version	register_en16931_codelist_tools	EN 16931 セマンティックコードリストの検索／チェック（単位、VAT カテゴリなど）を行います。EINVOICING_EN16931_CODELIST_DIR が必要です。

これらのツールのパラメーターに関する詳細は、mcp-einvoicing-core README をご覧ください。

使用例

例 1：請求書を検証する

1. invoice_validate(
     xml_base64="...",   # Base64-encoded ZUGFeRD XML
     strict=True
   )
   → {
       "is_valid": true,
       "profile": "EN_16931",
       "syntax": "CII",
       "error_count": 0,
       "warning_count": 2,
       "errors": [],
       "warnings": [...],
       "validator_used": "local_schematron"
     }

例 2：ドイツの税規則を照会する

2. tax_rules(query="reverse_charge", context="Bauleistungen")
   → {
       "results": [
         {
           "paragraph": "§13b Abs. 2 Nr. 5 UStG",
           "description_en": "Construction services (building contractor rule)",
           "vatex_code": "VATEX-EU-AE",
           "invoice_note": "Steuerschuldnerschaft des Leistungsempfängers (§13b UStG)"
         }
       ],
       "legal_disclaimer": "..."
     }

例 3：Peppol の登録状況を確認する

3. peppol_lookup_participant(
     identifier="123456789",   # bare USt-IdNr, normalized to 9930:DE123456789
     environment="production"
   )
   → {
       "is_registered": true,
       "participant_id": "9930:DE123456789",
       "supported_document_types": ["urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"],
       "smp_hostname": "b-...iso6523-actorid-upis.edelivery.tech.ec.europa.eu"
     }

例 4：請求書データを解析する

4. invoice_parse(xml_base64="...", include_raw_xml=False)
   → {
       "profile": "XRECHNUNG",
       "syntax": "CII",
       "invoice_number": "RE-2025-001",
       "invoice_date": "2025-01-15",
       "seller_name": "Muster GmbH",
       "buyer_name": "Käufer AG",
       "tax_inclusive_amount": "119.00",
       "currency_code": "EUR"
     }

アーキテクチャ

mcp-einvoicing-de (this package, standalone MCP server)
├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic models (all profiles)
├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* rules
├── KoSITValidator                     ← Remote validation tool (optional)
└── Tools: create / validate / parse / convert / datev_export / tax_rules
    (+ core Peppol tool plugin, mounted separately: lookup / send / DNS / codelists)

        ↑ extends
mcp-einvoicing-core (shared base, installed as dependency)
├── BaseDocumentGenerator / Validator / Parser
├── BaseInvoice, BaseParty … (Pydantic)
├── xml_utils, exceptions
└── EInvoicingMCPServer

ベンダー中立性

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

Peppol アクセスポイントは任意です。peppol_send による送信は利用可能なチャネルの 1 つであり、認定済みのアクセスポイントはすべて同じ AS4 プロファイルに対応しているため、プロバイダーの切り替えはコードの変更ではなく設定の変更で行えます。このパッケージは、ドイツの B2G 州ポータル（ZRE/OZG-RE）への直接送信には対応していません。

対応規格

規格	バージョン	プロファイル／構文
ZUGFeRD	2.5.2	MINIMUM、BASIC WL、BASIC、EN 16931、EXTENDED
XRechnung	3.0.2	CII（Cross Industry Invoice）、UBL（Universal Business Language）
KoSIT xrechnung-schematron ルールセット	2.6.0	XRechnung 3.0.2 の検証ルール（仕様そのものとは別のバージョン体系）
EN 16931	2017	電子請求書の欧州コアデータモデル
Peppol BIS	3.0	Billing 3.0（EN 16931 準拠）

注記： ZUGFeRD 2.x と XRechnung 3.x は、EN 16931 プロファイルレベルで同じ CII XML 構文を共有しています。そのため、データを損なうことなく両形式を相互変換できます。EXTENDED プロファイルは ZUGFeRD 固有であり、XRechnung に相当するものはありません。

リソース	リンク
FeRD ZUGFeRD 仕様	ferd-net.de
KoSIT XRechnung	xeinkauf.de
KoSIT 検証ツール	github.com/itplr-kosit/validationtool
EN 16931-1:2017	CEN
Peppol BIS Billing 3.0	docs.peppol.eu

テスト

# Install development dependencies
pip install -e ".[dev]"

# Run the full test suite
pytest tests/ -v

# With coverage report
pytest --cov=mcp_einvoicing_de --cov-report=term-missing

# Model tests only
pytest tests/test_models.py -v

コントリビューション

コントリビューションを歓迎します。大きな変更のプルリクエストを送信する前に、Issue を作成してください。

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make audit

その他の電子請求書発行 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 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。バージョン履歴の全容については、CHANGELOG.md をご覧ください。