mcp-einvoicing-de 🇩🇪

Name: mcp-einvoicing-de
Author: cmendezs

License PyPI version Python mcp-einvoicing-de MCP server

ドイツの電子請求書（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）サーバーです。ZUGFeRDまたはXRechnung請求書のライフサイクル全体をカバーする6つのツールを提供します：作成（CII/UBL XML）、EN 16931およびKoSIT Schematronルール（BR-DE-*）に基づく検証、既存の請求書ファイルの解析、プロファイルおよび構文変換、Peppol参加者登録ルックアップ（AS4）、およびドイツのVATルール（税区分、§13b UStGリバースチャージ、免税）の照会。すべてのZUGFeRD 2.xプロファイル（MINIMUMからEXTENDEDまで）およびXRechnung 3.x（CIIおよびUBL構文）をサポートしています。ライセンスはApache 2.0です。

基盤

このパッケージは、欧州の電子請求書MCPサーバー用の共通基盤ライブラリであるmcp-einvoicing-coreに基づいています。共通モデル、検証の抽象化、XMLヘルパー関数、例外階層を提供します。

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

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

🏗️ アーキテクチャ

mcp-einvoicing-de (dieses Paket — eigenständiger MCP-Server)
├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic-Modelle (alle Profile)
├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* Regeln
├── KoSITValidator                     ← Remote-Validierungstool (optional)
└── Tools: create / validate / parse / convert / peppol_check / tax_rules

        ↑ erweitert
mcp-einvoicing-core (gemeinsame Basis, als Abhängigkeit installiert)
├── BaseDocumentGenerator / Validator / Parser
├── BaseInvoice, BaseParty … (Pydantic)
├── xml_utils, exceptions
└── EInvoicingMCPServer

🚀 インストール

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]"

⚙️ 設定

v0.1.0では、サーバーに外部の認証情報は必要ありません。利用可能な環境変数は以下の通りです：

変数	説明	デフォルト
`EINVOICING_DE_LOG_LEVEL`	ログレベル (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`EINVOICING_DE_KOSIT_VALIDATOR_URL`	KoSIT検証ツールのURL（オプション、リモート検証用）	—
`EINVOICING_DE_PEPPOL_SMP_URL`	Peppol SMPルックアップURL（オプション）	—
`EINVOICING_DE_PDF_ENGINE`	PDF生成エンジン (`reportlab` または `pymupdf`)	`reportlab`

🤖 Claude Desktopへの統合

claude_desktop_config.json ファイルへの記述:

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

⌨️ Cursorへの統合

設定ファイル (~/.cursor/mcp.json またはプロジェクトディレクトリ内の .cursor/mcp.json):

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

🪐 Kiroへの統合

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

🧰 利用可能なMCPツール

ツール	説明
`invoice_create`	ZUGFeRDまたはXRechnung XML (CIIまたはUBL) を生成。PDF/A-3ハイブリッド対応を予定 (v0.2.0)
`invoice_validate`	EN 16931およびKoSIT Schematronルール (BR-DE-*) に基づいて請求書をチェック
`invoice_parse`	既存のZUGFeRDまたはXRechnungファイルから構造化データを抽出
`invoice_convert`	ZUGFeRDプロファイル間、またはZUGFeRD ↔ XRechnung間の変換
`peppol_check`	ドイツ企業のPeppol参加者登録を確認 (AS4)
`tax_rules`	ドイツの付加価値税ルール（税区分、§13b UStG、免税）を照会

使用例

例1 — 請求書の検証

1. invoice_validate(
     xml_base64="...",   # Base64-kodiertes 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_check(
     participant_id="0204:991-1234512345-06",
     environment="production"
   )
   → {
       "is_registered": true,
       "participant_id": "0204:991-1234512345-06",
       "document_type_supported": true,
       "access_point_url": "https://ap.example.de/as4",
       "transport_profile": "peppol-transport-as4-v2.0"
     }

例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"
     }

📚 サポートされている規格

規格	バージョン	プロファイル / 構文
ZUGFeRD	2.3	MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
XRechnung	3.x	CII (Cross Industry Invoice), UBL (Universal Business Language)
EN 16931	—	電子請求書のための欧州コアデータモデル
Peppol BIS	3.0	Billing 3.0 (DE PINT)

注意: 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

🧪 テスト

# Entwicklungsabhängigkeiten installieren
pip install -e ".[dev]"

# Gesamte Testsuite ausführen
pytest tests/ -v

# Mit Abdeckungsbericht
pytest --cov=mcp_einvoicing_de --cov-report=term-missing

# Nur Modell-Tests
pytest tests/test_models.py -v

ロードマップ

バージョン	機能
v0.1.0 (現在)	ツール: create, validate, parse, convert, peppol_check, tax_rules
v0.2.0	`reportlab` / `PyMuPDF` を使用したPDF/A-3埋め込み (ZUGFeRDハイブリッド)
v0.3.0	KoSITオンラインバリデーターの完全統合
v0.4.0	Peppol AS4直接送信
v0.5.0	DATEVエクスポート形式
v1.0.0	本番環境対応、EN 16931の完全網羅

貢献

貢献を歓迎します。重要な変更のプルリクエストを送信する前に、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-facture-electronique-fr
🇮🇹 イタリア	mcp-fattura-elettronica-it
🇩🇪 ドイツ	mcp-einvoicing-de

📄 ライセンス

このプロジェクトは Apache-2.0ライセンス の下で提供されています。詳細は LICENSE ファイルを参照してください。

プロジェクト管理: cmendezs。ZUGFeRDまたはXRechnung仕様の実装に関する質問は、Issueを作成してください。

mcp-einvoicing-de