mcp-einvoicing-be
mcp-einvoicing-be 🇧🇪
English | Francais | Nederlands
はじめに
mcp-einvoicing-be は、ベルギー電子請求書発行のためのツールを公開するMCP(Model Context Protocol)サーバーです。これはベルギーの電子請求書発行エコシステム全体をカバーしています: Peppol BIS Billing 3.0、UBL 2.1、および公共部門向け請求書発行のためのMercuriusネットワーク。このサーバーは、国固有のmcp-einvoicing-*サーバーファミリーの一部であり、すべてmcp-einvoicing-core上に構築されています。mcp-einvoicing-coreは、共有の検証エンジン、UBL抽象化、およびPeppolネットワークユーティリティを提供します。
Related MCP server: mcp-facture-electronique-fr
インストール
要件
Python ≥ 3.11
mcp-einvoicing-core(依存関係として自動的にインストールされます)
uvの使用(推奨)
uv add mcp-einvoicing-bepipの使用
pip install mcp-einvoicing-beソースから
git clone https://github.com/cmendezs/mcp-einvoicing-be.git
cd mcp-einvoicing-be
uv sync --all-extras設定
MCPクライアント設定にサーバーを追加します。Claude Desktopの場合は、claude_desktop_config.jsonを編集します:
{
"mcpServers": {
"einvoicing-be": {
"command": "uvx",
"args": ["mcp-einvoicing-be"]
}
}
}ローカル開発インストールの場合:
{
"mcpServers": {
"einvoicing-be": {
"command": "uv",
"args": ["run", "mcp-einvoicing-be"],
"cwd": "/path/to/mcp-einvoicing-be"
}
}
}環境変数
変数 | 説明 | デフォルト |
| ベルギーBCE/KBO企業データベース用のAPIキー | — |
| Peppol環境: |
|
| SMLルックアップURLの上書き | (自動) |
| ログレベル: |
|
利用可能なツール
validate_invoice_be
UBL 2.1 XML請求書を検証します。peppol-bis-3/pint-euプロファイルは、実際のコンパイル済みPeppol BIS 3.0 Schematronアーティファクトが利用可能になるまで(パッケージローカルの近似値は使用されません — CHANGELOG.md v0.7.0を参照)、明示的に「利用不可」の結果を報告します。mercuriusプロファイルは、Mercurius固有のオーバーレイ(エンドポイントスキーム、PO参照)を実行しますが、ベースのEN 16931/Peppol BIS 3.0準拠はチェックしません。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | 生のUBL 2.1 XMLコンテンツ |
|
| いいえ |
|
valid、errors、warnings(それぞれ、失敗したルールIDと人間が読めるメッセージを含む)を持つValidationResultを返します。
generate_invoice_be
構造化データから有効なUBL 2.1ベルギー電子請求書XMLドキュメントを生成します。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | 請求書フィールド(以下の |
|
| いいえ |
|
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に変換します。検証前の最初のステップとして役立ちます。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | ソース請求書データ( |
lookup_vat_be
ベルギーの事業者番号(VAT番号)をBCE/KBO公開データベースに対して検索します。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | ベルギーのVAT/事業者番号。例: |
事業者名、登録住所、法的ステータス、およびNACE活動コードを返します。
check_peppol_participant_be
SMP/SMLネットワークに問い合わせることで、ベルギーの企業がPeppol参加者として登録されているかどうかを確認します。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | Peppol参加者ID(例: |
登録ステータス、サポートされているドキュメントタイプ識別子、およびSMPアクセスポイントエンドポイントURLを返します。
parse_ubl_invoice_be
UBL 2.1 XML請求書(Peppol BIS 3.0)を構造化された辞書に解析します。王室令第1号第13条の4によって要求される必須の受信機能を満たします。
パラメータ | タイプ | 必須 | 説明 |
|
| はい | 生のUBL 2.1 XML請求書コンテンツ |
成功時は{"success": true, "invoice": {...}, "warnings": []}を、解析失敗時は{"success": false, "error": "..."}を返します。
get_invoice_types_be
各プロファイルのUBL customizationID および profileID 値とともに、サポートされているベルギー電子請求書ドキュメントタイプ(請求書、クレジットノート、デビットノート)のリストを返します。
入力パラメータは必要ありません。
Mercurius経由のB2G
Mercuriusはベルギー連邦公共部門の電子請求書発行プラットフォームです。これは独立したAPIではなく、Peppolネットワークレシーバーとして動作します。B2G請求書は、0208スキーム(KBO/BCE 10桁の事業者番号)の当局の参加者IDを使用して、標準の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, check_peppol_participant_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
└── LICENSEmcp-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チェックデジット検証
必須受信(第13条の4)のためのUBL 2.1請求書解析
ベルギーPeppolコーナー固有の
customizationIDおよびprofileID値
貢献
貢献は歓迎します。プルリクエストを送信する前に、重要な変更については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サーバー
国 | サーバー |
🌍 グローバル | |
🇧🇪 ベルギー | |
🇧🇷 ブラジル | |
🇫🇷 フランス | |
🇩🇪 ドイツ | |
🇮🇹 イタリア | |
🇵🇱 ポーランド | |
🇪🇸 スペイン |
ライセンス
このプロジェクトはApache 2.0の下でライセンスされています — 詳細はLICENSEを参照してください。
変更履歴
バージョン別の変更の完全なリストについてはCHANGELOG.mdを参照してください。
Available Tools
50 toolsbuild_mls_messageA
Build a document-level MLS response and return it base64-encoded.
For per-line responses, build the document directly with
mcp_einvoicing_core.peppol.mls.build_mls.
Inputs: mls_id (required), issue_date (required), sender_value (required), response_code (required), +7 more. Returns: object
check_allowance_reason_codeA
Check whether code is a recognized allowance reason code.
Inputs: code (required). Returns: object
check_charge_reason_codeB
Check whether code is a recognized charge reason code.
Inputs: code (required). Returns: object
check_country_codeA
Check whether code is a recognized ISO 3166-1 alpha-2 country code.
Inputs: code (required). Returns: object
check_currency_codeA
Check whether code is a recognized ISO 4217 currency code.
Inputs: code (required). Returns: object
check_document_name_codeA
Check whether code is a recognized UNCL1001 document name code.
Inputs: code (required). Returns: object
check_document_type_id_in_codelistB
Check whether a (scheme, value) pair is a recognized Peppol document type identifier.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Searches all entries regardless of state, so a historical (deprecated
or removed) document type is still reported as found.
Inputs: value (required), scheme (required). Returns: object
check_eas_codeA
Check whether code is a recognized Electronic Address Scheme code.
Inputs: code (required). Returns: object
check_icd_codeC
Check whether code is a recognized ISO 6523 ICD code.
Inputs: code (required). Returns: object
check_item_type_codeB
Check whether code is a recognized item type identification code.
Inputs: code (required). Returns: object
check_mime_codeA
Check whether code is a recognized MIME type for embedded attachments.
Inputs: code (required). Returns: object
check_participant_id_scheme_in_codelistA
Check whether a 4-digit ISO 6523 ICD code (e.g. "0208") is a recognized Peppol scheme.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: icd (required). Returns: object
check_payment_means_codeA
Check whether code is a recognized UNCL4461 payment means code.
Inputs: code (required). Returns: object
check_process_id_in_codelistB
Check whether a (scheme, value) pair is a recognized Peppol process identifier.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: value (required), scheme (required). Returns: object
check_reference_qualifier_codeA
Check whether code is a recognized UNCL1153 reference qualifier code.
Inputs: code (required). Returns: object
check_vat_category_codeA
Check whether code is a recognized UNCL5305 VAT category code.
Inputs: code (required). Returns: object
check_vatex_codeA
Check whether code is a recognized VATEX VAT exemption reason code.
Inputs: code (required). Returns: object
generate_invoice_beA
Generate a valid UBL 2.1 Belgian e-invoice XML document from structured data.
Applies the correct customizationID and profileID for the selected Belgian Peppol profile. The output XML is ready for submission to the Peppol network or the Mercurius platform.
Returns a dict with:
xml: the generated UBL 2.1 XML stringcustomization_id: the UBL customizationID applied (BT-24)profile_id: the UBL profileID applied (BT-23)
Inputs: invoice_data (required), profile. Returns: object
get_en16931_codelist_versionA
Report the CEF EN 16931 code-list release version(s) currently configured locally.
Inputs: no named parameters. Returns: object
get_invoice_types_beA
Return the supported Belgian e-invoice document types.
Includes invoice (380), credit note (381), and debit note (383) with their
UBL customizationID and profileID values for each supported profile
(Peppol BIS Billing 3.0).
Inputs: no named parameters. Returns: object
get_peppol_codelist_versionA
Report the OpenPeppol eDEC code list release version(s) currently configured locally.
Inputs: no named parameters. Returns: object
list_allowance_reason_codesA
List allowance reason codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_charge_reason_codesA
List charge reason codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_country_codesA
List ISO 3166-1 alpha-2 country codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_currency_codesA
List ISO 4217 currency codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_document_name_codesA
List UNCL1001 document name codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_document_type_idsA
List Peppol document type identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
list_eas_codesA
List Electronic Address Scheme (EAS) codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_icd_codesA
List ISO 6523 ICD codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_item_type_codesA
List item type identification codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_mime_codesA
List recognized MIME types for embedded attachments.
Inputs: no named parameters. Returns: object
list_participant_id_schemesA
List Peppol participant identifier (ICD) schemes from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR to point at a local copy of
the eDEC "Participant Identifier Schemes" GeneriCode export (not
bundled with this package, no confirmed redistribution rights, see
mcp_einvoicing_core.peppol.codelists module docstring).
Inputs: active_only. Returns: object
list_payment_means_codesA
List UNCL4461 payment means codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_process_idsA
List Peppol process identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
list_reference_qualifier_codesA
List UNCL1153 reference qualifier codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_spis_use_case_idsA
List Peppol SPIS use case identifiers from the OpenPeppol eDEC code list.
Requires EINVOICING_PEPPOL_CODELIST_DIR (see list_participant_id_schemes).
Inputs: active_only. Returns: object
list_vat_category_codesA
List UNCL5305 VAT category codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_vatex_codesA
List VATEX (VAT exemption reason) codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
lookup_vat_beA
Look up a Belgian enterprise number against the BCE/KBO public database.
Accepts the number with or without the 'BE' prefix and with or without dots/spaces. Returns the enterprise's legal name, registered address, legal form, status, and NACE activity codes.
Optionally set the BCE_API_KEY environment variable for authenticated
access to the full BCE dataset.
Inputs: vat_number (required). Returns: object
parse_ubl_invoice_beA
Parse a UBL 2.1 XML invoice into a structured dict.
Accepts a Peppol BIS Billing 3.0 or EU PINT v1.0.1 UBL 2.1 document and extracts the EN 16931 core field set (header, parties, lines, tax breakdown, totals) plus Belgian extensions (OGM/VCS reference, endpoint scheme info).
Returns {"success": true, "invoice": {...}, "be_extensions": {...}, "warnings": []}
on success, or {"success": false, "error": "..."} on parse failure.
Inputs: xml_content (required). Returns: object
peppol_directory_searchA
Search the Peppol Directory for registered participants.
Public, unauthenticated search (no relation to SMP lookup). At least one of q/participant/name/country/doctype must be supplied.
Inputs: q, name, country, doctype, +4 more. Returns: object
peppol_get_service_endpointA
Fetch the AS4 endpoint for a Peppol participant's document type.
Resolves the SMP hostname via DNS, then fetches service metadata for
document_type_id. If the SMP returns a redirect, the result's
redirect_url is set and endpoint_url is None; callers must not
follow more than one redirect hop (SMP 1.4.0 §3.2).
Inputs: identifier (required), environment, document_type_id. Returns: object
peppol_lookup_participantA
Check whether a business is registered on the Peppol network.
Performs a DNS-over-HTTPS U-NAPTR lookup followed by an SMP service-group request to determine registration status and the list of supported document type identifiers.
Inputs: identifier (required), environment. Returns: object
peppol_sendA
Send a UBL/CII invoice to a Peppol participant via AS4.
Looks up the recipient's AS4 endpoint (SMP), builds the ebMS3/AS4 envelope, and transmits it using the supplied signing credentials.
Inputs: sender_id (required), certificate_path (required), private_key_path (required), invoice_xml_base64 (required), +4 more. Returns: object
resolve_peppol_dnsA
Resolve the SMP hostname for a Peppol participant via DNS only.
Performs the raw U-NAPTR (SML) lookup without fetching the SMP service group, useful for diagnosing whether a participant is registered in the SML independently of SMP reachability.
Inputs: identifier (required), environment. Returns: object
transform_to_ublA
Convert a structured JSON invoice payload to UBL 2.1 XML.
Unlike generate_invoice_be, this tool does not run validation after
transformation. Intended as a conversion step when the caller will validate
separately or submit directly to a platform that performs its own validation.
Returns a dict with:
xml: the generated UBL 2.1 XML stringwarnings: list of non-fatal issues detected during transformation
Inputs: data (required). Returns: object
validate_eusr_reportA
Validate a Peppol End User Statistics Report (EUSR) document.
Runs XSD structural validation, then Schematron business rules
(requires the [xslt2] optional extra).
Inputs: report_xml_base64 (required). Returns: object
validate_invoice_beA
Validate a UBL 2.1 XML invoice against Belgian business rules.
For 'peppol-bis-3'/'pint-eu': checks the CEN EN16931 base rules (structural + arithmetic/totals, ~50 BR-* rules) via a compiled Schematron. Does NOT check the Peppol-specific overlay (profile ID registration, EndpointID scheme, narrowed code lists) — the result's metadata.scope is "en16931-base-only", and a warning is included. This is not a full Peppol BIS3 conformance check; a document that passes may still be rejected by a real Peppol Access Point (no confirmed OpenPeppol redistribution rights for the overlay rules). For 'mercurius': applies the Mercurius-specific overlay rules only (endpoint scheme, PO reference) — also not full EN16931/Peppol base compliance. Returns a structured result with per-rule error and warning messages.
Inputs: xml (required), profile. Returns: object
validate_mls_messageA
Validate a Peppol Message Level Status (MLS) document.
Runs the bundled MLS Schematron rules (requires the [xslt2]
optional extra). No bespoke MLS XSD exists — full UBL 2.1 XSD
validation is out of scope.
Inputs: mls_xml_base64 (required). Returns: object
validate_tsr_reportA
Validate a Peppol Transaction Statistics Report (TSR) document.
Runs XSD structural validation, then Schematron business rules
(requires the [xslt2] optional extra).
Inputs: report_xml_base64 (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 50 tools
The tool set has many code-list helpers (list_*/check_*), but each targets a specific code list and descriptions clearly distinguish them. Minor overlap exists between check_icd_code and check_participant_id_scheme_in_codelist, and among Peppol lookup/send tools, but explicit scope wording mitigates confusion.
Almost all tools use snake_case with a verb_noun or verb_noun_context pattern (validate_invoice_be, list_eas_codes, check_eas_code). Some inconsistency appears with domain prefixes (peppol_lookup_participant) and the _be suffix, but the overall convention is predictable.
50 tools is excessive for this domain; many are paired list/check code-list operations that could be consolidated or exposed as a single parameterized tool. The count sits at the rubric's extreme-mismatch threshold.
Core e-invoicing lifecycle is covered: generation, validation, parsing, transformation, code lists, VAT lookup, Peppol discovery, sending, and report validation. Gaps include no full Peppol overlay validation (explicitly out of scope) and no receive/inbox operations, but the surface is largely complete for creation and submission workflows.
Maintenance
Related MCP Connectors
Create and check Peppol BIS 3.0 e-invoices; look up EU VAT numbers (VIES) and Peppol IDs.
Generate, validate and read EN 16931 and Peppol BIS 3.0 e-invoices, in UBL and CII.
Validate, generate, convert and extract EN 16931 e-invoices for businesses.
Validate, generate & convert EU e-invoices (UBL, CII, XRechnung, Factur-X) — EN 16931 pre-validated.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for DACH e-invoicing. Create XRechnung (UBL) and ZUGFeRD 2.3 (Factur-X CII) invoices, validate against EN 16931 rules, extract data from XML, and convert between UBL, CII and JSON formats.650 npm2MIT
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for French Electronic Invoicing (NF XP Z12-013). Provide tools to validate, generate, and explore API specifications for PDP/OD interoperability.341Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for German Electronic Invoicing (ZUGFeRD 2.x / XRechnung 3.x). Provides tools to validate, generate, parse, and convert invoices compliant with EN 16931 and KoSIT.50112 PyPI2Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Spanish Electronic Invoicing. Provides tools to generate, validate, and submit invoices across VERI\*FACTU, Facturae/FACe, SII, TicketBAI, and Crea y Crece B2B.20169 PyPI3Apache 2.0