Skip to main content
Glama
mcp-einvoicing-be

mcp-einvoicing-be

mcp-einvoicing-be 🇧🇪

English | Francais | Nederlands

PyPI version Python License mcp-einvoicing-be MCP server


简介

mcp-einvoicing-be 是一个 MCP(模型上下文协议) 服务器,提供用于比利时电子发票的工具。它涵盖了完整的比利时电子发票生态系统:Peppol BIS Billing 3.0、UBL 2.1 以及用于公共部门发票的 Mercurius 网络。该服务器是 mcp-einvoicing-* 系列国家特定服务器的一部分,所有这些服务器都构建在 mcp-einvoicing-core 之上,后者提供了共享的验证引擎、UBL 抽象和 Peppol 网络工具。


Related MCP server: mcp-facture-electronique-fr

安装

要求

使用 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

配置

将服务器添加到您的 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_API_KEY

比利时 BCE/KBO 企业数据库的 API 密钥

—

PEPPOL_ENV

Peppol 环境:production 或 test

production

PEPPOL_SML_URL

覆盖 SML 查找 URL

(自动)

LOG_LEVEL

日志级别:DEBUG、INFO、WARNING、ERROR

INFO


可用工具

validate_invoice_be

验证 UBL 2.1 XML 发票。peppol-bis-3/pint-eu 配置文件会报告显式的“不可用”结果,直到有真正的编译版 Peppol BIS 3.0 Schematron 工件可用(不使用包本地近似值——请参阅 CHANGELOG.md v0.7.0)。mercurius 配置文件运行 Mercurius 特定的覆盖层(端点方案、采购订单引用),但不检查基础 EN 16931/Peppol BIS 3.0 合规性。

参数

类型

必需

描述

xml

string

是

原始 UBL 2.1 XML 内容

profile

string

否

peppol-bis-3(默认)或 mercurius

返回一个 ValidationResult,包含 valid、errors 和 warnings(每个都带有失败的规则 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

根据 BCE/KBO 公共数据库查询比利时企业编号(增值税号)。

参数

类型

必需

描述

vat_number

string

是

比利时增值税/企业编号,例如 BE0428759497 或 0123456789

返回企业名称、注册地址、法律状态和 NACE 活动代码。


check_peppol_participant_be

通过查询 SMP/SML 网络,检查比利时公司是否注册为 Peppol 参与者。

参数

类型

必需

描述

identifier

string

是

Peppol 参与者 ID(例如 0088:BE0428759497)或纯比利时增值税号

返回注册状态、支持的文档类型标识符以及 SMP 接入点端点 URL。


parse_ubl_invoice_be

将 UBL 2.1 XML 发票(Peppol BIS 3.0)解析为结构化字典。满足第 1 号皇家法令第 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 是比利时联邦公共部门电子发票平台。它作为 Peppol 网络接收方 运行,而不是一个单独的 API。B2G 发票通过标准 Peppol 网络提交,使用当局在 0208 方案中的参与者 ID(KBO/BCE 10 位企业编号)。接入点自动将发票路由到 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
└── 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 在此基础上添加了比利时特定的逻辑:

  • Mercurius 网络覆盖规则验证(基于 XPath),用于 B2G 发票

  • BCE/KBO 企业数据库集成

  • 比利时增值税号规范化(BTW/TVA 格式)和 OGM/VCS 校验位验证

  • 用于强制性接收(第 13quater 条)的 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 服务器

国家/地区

服务器

🌍 全球

mcp-einvoicing-core

🇧🇪 比利时

mcp-einvoicing-be

🇧🇷 巴西

mcp-nfe-br

🇫🇷 法国

mcp-facture-electronique-fr

🇩🇪 德国

mcp-einvoicing-de

🇮🇹 意大利

mcp-fattura-elettronica-it

🇵🇱 波兰

mcp-ksef-pl

🇪🇸 西班牙

mcp-facturacion-electronica-es


许可证

本项目采用 Apache 2.0 许可证——详情请参阅 LICENSE。


更新日志

请参阅 CHANGELOG.md 获取按版本列出的完整更改列表。

Available Tools

50 tools
build_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 string

  • customization_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_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 string

  • warnings: 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

    A3.5/5.0

    Scored across 50 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      6
      50 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      34
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      50
      112 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      20
      169 PyPI
      3
      Apache 2.0