mcp-einvoicing-be

mcp-einvoicing-be 🇧🇪

英語 | フランス語 | オランダ語

---

はじめに

mcp-einvoicing-be は、ベルギーの電子請求書発行ツールを提供する MCP（Model Context Protocol） サーバーです。ベルギーの電子請求書発行エコシステム全体をカバーしており、Peppol BIS Billing 3.0、UBL 2.1、公共部門の請求書発行に使われる Mercurius ネットワークに対応しています。このサーバーは、国別サーバー群 mcp-einvoicing-* の一つです。これらはすべて、共通の検証エンジン、UBL 抽象化機能、Peppol ネットワークユーティリティを提供する mcp-einvoicing-core を基盤として構築されています。

インストール

要件

• Python ≥ 3.11
• mcp-einvoicing-core（依存関係として自動的にインストールされます）

uv を使用する場合（推奨）

uv add mcp-einvoicing-be

pip を使用する場合

pip install mcp-einvoicing-be

ソースからインストール

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

設定

環境変数

変数	説明	デフォルト
BCE_API_KEY	ベルギー BCE/KBO 企業データベースの API キー	—
PEPPOL_ENV	Peppol 環境：production または test	production
PEPPOL_SML_URL	SML 検索 URL の上書き	（自動）
EINVOICING_PEPPOL_CODELIST_DIR	OpenPeppol eDEC Code Lists の独自コピーを格納したローカルディレクトリ。コードリストツールに必要です（このパッケージには含まれていません。mcp-einvoicing-core の README を参照してください）	—
EINVOICING_EN16931_CODELIST_DIR	CEF「Digital Building Blocks」EN 16931 セマンティックコードリストの独自コピーを格納したローカルディレクトリ。EN 16931 コードリストツールに必要です（同梱されていません。mcp-einvoicing-core の README を参照してください）	—
LOG_LEVEL	ログレベル：DEBUG、INFO、WARNING、ERROR	INFO

EUSR/TSR レポート作成ツールおよび MLS ツールで Schematron 検証を行うには、追加で [xslt2] エクストラ（pip install "mcp-einvoicing-be[xslt2]"）が必要です。

Claude Desktop との連携

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

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "your-bce-api-key",
        "PEPPOL_ENV": "production"
      }
    }
  }
}

ローカル開発用にインストールした場合：

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uv",
      "args": ["run", "mcp-einvoicing-be"],
      "cwd": "/path/to/mcp-einvoicing-be"
    }
  }
}

Cursor との連携

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

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

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "your-bce-api-key",
        "PEPPOL_ENV": "production"
      }
    }
  }
}

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

Kiro との連携

Kiro は専用の設定ファイルを通じて MCP サーバーに対応しています。設定には次の 2 つの範囲があります。

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

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "your-bce-api-key",
        "PEPPOL_ENV": "production"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

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

利用可能なツール

validate_invoice_be

UBL 2.1 XML 請求書を検証します。peppol-bis-3／pint-eu プロファイルでは、CEN EN 16931 の基本ルール（約50件の BR-* 構造・算術ルール）に対して、実際の Schematron 検証を実行します（mcp-einvoicing-core にバンドルされた基本 Schematron を使用します。CHANGELOG.md v0.8.0 を参照）。Peppol 固有のオーバーレイルールはチェックしません（OpenPeppol による再配布権を確認できていないため）。結果には対象範囲を明示する en16931-base-only の警告が含まれ、Peppol BIS3 への完全な準拠を示すものとして解釈しないでください。mercurius プロファイルでは Mercurius 固有のオーバーレイ（エンドポイントスキーム、PO 参照）を実行しますが、基本の EN 16931／Peppol BIS 3.0 への準拠はチェックしません。

パラメーター	型	必須	説明
xml	string	はい	生の UBL 2.1 XML コンテンツ
profile	string	いいえ	peppol-bis-3（デフォルト）または mercurius

valid、errors、warnings を含む ValidationResult を返します（各項目には、失敗したルール ID と人が読めるメッセージが含まれます）。

---

generate_invoice_be

構造化データから有効な UBL 2.1 ベルギー電子請求書 XML ドキュメントを生成します。

パラメーター	型	必須	説明
invoice_data	object	はい	請求書のフィールド（以下の InvoiceInput スキーマを参照）
profile	string	いいえ	peppol-bis-3（デフォルト）

InvoiceInput オブジェクトでサポートされる項目は次のとおりです。

{
  "invoice_number": "INV-2024-001",
  "issue_date": "2024-01-15",
  "due_date": "2024-02-14",
  "currency_code": "EUR",
  "supplier": { "name": "...", "vat_number": "BE0428759497", "address": {...} },
  "customer": { "name": "...", "vat_number": "BE0403170701", "address": {...} },
  "lines": [{ "description": "...", "quantity": 1, "unit_price": 100.00, "vat_rate": 21.0 }]
}

UBL 2.1 XML 文字列を返します。

---

transform_to_ubl

構造化された JSON 請求書ペイロードを、完全な検証を行わずに UBL 2.1 XML に変換します。検証前の最初のステップとして便利です。

パラメーター	型	必須	説明
data	object	はい	変換元の請求書データ（InvoiceInput と同じ形式）

---

lookup_vat_be

ベルギーの企業番号（VAT 番号）を BCE/KBO 公開データベースで検索します。

パラメーター	型	必須	説明
vat_number	string	はい	ベルギーの VAT／企業番号。例：BE0428759497 または 0123456789

企業名、登録住所、法的ステータス、NACE 活動コードを返します。

---

Peppol ネットワークツール

Peppol 参加者の検索、サービスエンドポイントの検索、DNS のみの診断、AS4 送信、Peppol Directory 検索、OpenPeppol eDEC コードリストツールは、共有コア Peppol ツールプラグイン（mcp_einvoicing_core.peppol.tools.register_peppol_tools）によって提供されます。このプラグインは、BE 固有の識別子アダプターとともに server.py にマウントされています。ベルギーの VAT 番号のみの値（例：0428759497 または BE0428759497）は Peppol スキーム 0208:<digits>（KBO/BCE 企業番号）に正規化されます。すでにスキームが付与された識別子（例：0208:0428759497）は変更せずに渡されます。

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 をご覧ください。

---

parse_ubl_invoice_be

UBL 2.1 XML 請求書（Peppol BIS 3.0）を構造化された dict に解析します。勅令第 1 号 Art. 13quater で義務付けられている受信機能を満たします。

パラメーター	型	必須	説明
xml_content	string	はい	UBL 2.1 XML 請求書の生コンテンツ

成功時は {"success": true, "invoice": {...}, "warnings": []} を返し、解析に失敗した場合は {"success": false, "error": "..."} を返します。

---

get_invoice_types_be

サポート対象のベルギーの電子請求書文書タイプ（請求書、クレジットノート、デビットノート）と、各プロファイルの UBL customizationID および profileID 値の一覧を返します。

入力パラメーターは不要です。

Mercurius 経由の B2G

Mercurius は、ベルギー連邦政府の公共部門向け電子請求書プラットフォームです。独立した API ではなく、Peppol ネットワークの受信者として機能します。B2G 請求書は、当局の参加者 ID を 0208 スキーム（KBO/BCE の 10 桁の企業番号）で指定し、標準の Peppol ネットワークを通じて送信されます。アクセスポイントが請求書を Mercurius に自動的にルーティングします。Mercurius 専用の送信エンドポイントや API キーは不要です。

アーキテクチャ

mcp-einvoicing-be/
├── src/
│   └── mcp_einvoicing_be/
│       ├── __init__.py
│       ├── server.py              # MCP server entry point & tool registration
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── validation.py      # validate_invoice_be
│       │   ├── generation.py      # generate_invoice_be
│       │   ├── transformation.py  # transform_to_ubl
│       │   ├── parsing.py         # parse_ubl_invoice_be
│       │   └── lookup.py          # lookup_vat_be, get_invoice_types_be
│       ├── models/
│       │   ├── __init__.py
│       │   ├── invoice.py         # InvoiceInput, InvoiceLine, ValidationResult
│       │   └── party.py           # Supplier, Customer, Address
│       ├── standards/
│       │   ├── __init__.py
│       │   ├── peppol_bis_3.py    # Peppol BIS Billing 3.0 rules & customization IDs
│       │   ├── ubl.py             # UBL 2.1 namespace constants & XML helpers
│       │   ├── pint_be.py         # PINT-BE placeholder (removed in v0.4.0)
│       │   └── mercurius.py       # Mercurius network config & overlay rules
│       └── utils/
│           ├── __init__.py
│           └── helpers.py         # VAT number normalization, date formatting, etc.
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_tools/
│   │   ├── __init__.py
│   │   ├── test_validation.py
│   │   ├── test_generation.py
│   │   └── test_transformation.py
│   └── fixtures/
│       ├── invoice_valid_peppol.xml
│       ├── invoice_valid_pint_be.xml
│       └── invoice_invalid.xml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── publish.yml
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

mcp-einvoicing-core との関係

mcp-einvoicing-core が提供するもの：

• 共有 UBL 2.1/2.3 XML 解析およびシリアライズユーティリティ
• EN 16931 の基本検証ルール（構文＋セマンティック）
• Peppol ネットワーククライアント（SMP ルックアップ、SML 解決）
• 共通の Pydantic 基底モデル（BaseInvoice、BaseParty、BaseValidationResult）

mcp-einvoicing-be が追加するベルギー固有のロジック：

• B2G 請求向けの Mercurius ネットワークオーバーレイルール検証（XPath ベース）
• BCE/KBO 企業データベースとの統合
• ベルギーの VAT 番号の正規化（BTW/TVA 形式）および OGM/VCS のチェックディジット検証
• 義務付けられている受信機能のための UBL 2.1 請求書解析（Art. 13quater）
• ベルギーの Peppol コーナー固有の customizationID および profileID 値

ベンダー中立性

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

Peppol アクセスポイントは必要ですが、認定されたアクセスポイントはすべて同じ AS4 プロファイルに対応しているため、プロバイダーの切り替えはコードの変更ではなく、設定の変更で済みます。

貢献

貢献を歓迎します。大きな変更を提出する前に、issue を作成して相談してください。

git clone https://github.com/cmendezs/mcp-einvoicing-be.git
cd mcp-einvoicing-be
uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run mypy src

すべてのプルリクエストは、次の条件を満たす必要があります。

• テストスイート全体に合格すること（pytest）
• リントに合格すること（ruff check）
• 型チェックに合格すること（mypy）
• 動作を変更した場合は、テストを追加または更新すること
• 検証の問題を修正する場合は、該当するルール ID を記載すること

詳細なガイドラインについては、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 をご覧ください。