Skip to main content
Glama
mcp-einvoicing-be

mcp-einvoicing-be

mcp-einvoicing-be 🇧🇪

영어 | 프랑스어 | 네덜란드어

PyPI version Python License mcp-einvoicing-be MCP server


소개

mcp-einvoicing-be는 벨기에 전자송장 발행을 위한 도구를 제공하는 MCP (Model Context Protocol) 서버입니다. 이 서버는 벨기에 전자송장 생태계 전체를 포괄합니다: 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 재정의

(auto)

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

valid, errors, warnings (각각 실패한 규칙 ID와 사람이 읽을 수 있는 메시지를 포함)가 있는 ValidationResult를 반환합니다.


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 번호)를 조회합니다.

매개변수

유형

필수

설명

vat_number

string

예

벨기에 VAT/기업 번호, 예: BE0428759497 또는 0123456789

기업명, 등록 주소, 법적 상태 및 NACE 활동 코드를 반환합니다.


check_peppol_participant_be

SMP/SML 네트워크를 쿼리하여 벨기에 회사가 Peppol 참가자로 등록되어 있는지 확인합니다.

매개변수

유형

필수

설명

identifier

string

예

Peppol 참가자 ID (예: 0088:BE0428759497) 또는 일반 벨기에 VAT 번호

등록 상태, 지원되는 문서 유형 식별자 및 SMP 액세스 포인트 엔드포인트 URL을 반환합니다.


parse_ubl_invoice_be

UBL 2.1 XML 송장(Peppol BIS 3.0)을 구조화된 딕셔너리로 파싱합니다. 왕령 제1호 제13조의4에서 요구하는 필수 수신 기능을 충족합니다.

매개변수

유형

필수

설명

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 송장은 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
└── 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 송장 파싱 (제13조의4)

  • 벨기에 Peppol 코너에 특화된 customizationID 및 profileID 값


기여

기여를 환영합니다. 중요한 변경 사항은 풀 리퀘스트를 제출하기 전에 이슈를 열어 논의해 주세요.

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