{
  "markdown": "# mcp-einvoicing-be 🇧🇪\n\n[English](README.md) | [Francais](README.fr.md) | [Nederlands](README.nl.md)\n\n<!-- mcp-name: io.github.cmendezs/mcp-einvoicing-be -->\n\n[![PyPI version](https://badge.fury.io/py/mcp-einvoicing-be.svg)](https://badge.fury.io/py/mcp-einvoicing-be)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-einvoicing-be.svg)](https://pypi.org/project/mcp-einvoicing-be/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![mcp-einvoicing-be MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-be/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-be)\n\n---\n\n## Introduction\n\n`mcp-einvoicing-be` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes tools for Belgian electronic invoicing. It covers the full Belgian e-invoicing ecosystem: **Peppol BIS Billing 3.0**, **UBL 2.1**, and the **Mercurius** network for public-sector invoicing. The server is part of the `mcp-einvoicing-*` family of country-specific servers, all built on top of [`mcp-einvoicing-core`](https://github.com/cmendezs/mcp-einvoicing-core), which provides the shared validation engine, UBL abstractions, and Peppol network utilities.\n\n## Installation\n\n### Requirements\n\n- Python ≥ 3.11\n- [`mcp-einvoicing-core`](https://github.com/cmendezs/mcp-einvoicing-core) (installed automatically as a dependency)\n\n### Using `uv` (recommended)\n\n```bash\nuv add mcp-einvoicing-be\n```\n\n### Using `pip`\n\n```bash\npip install mcp-einvoicing-be\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cmendezs/mcp-einvoicing-be.git\ncd mcp-einvoicing-be\nuv sync --all-extras\n```\n\n## Configuration\n\n### Environment variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `BCE_API_KEY` | API key for the Belgian BCE/KBO enterprise database | — |\n| `PEPPOL_ENV` | Peppol environment: `production` or `test` | `production` |\n| `PEPPOL_SML_URL` | Override the SML lookup URL | (auto) |\n| `EINVOICING_PEPPOL_CODELIST_DIR` | Local directory containing your own copy of the OpenPeppol eDEC Code Lists, required by the codelist tools (not bundled with this package; see `mcp-einvoicing-core` README) | — |\n| `EINVOICING_EN16931_CODELIST_DIR` | Local directory containing your own copy of the CEF \"Digital Building Blocks\" EN 16931 semantic code lists, required by the EN 16931 codelist tools (not bundled; see `mcp-einvoicing-core` README) | — |\n| `LOG_LEVEL` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |\n\nThe EUSR/TSR reporting and MLS tools additionally require the `[xslt2]` extra (`pip install \"mcp-einvoicing-be[xslt2]\"`) for Schematron validation.\n\n## Claude Desktop integration\n\nTo use this server with Claude, add this configuration to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-be\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-be\"],\n      \"env\": {\n        \"BCE_API_KEY\": \"your-bce-api-key\",\n        \"PEPPOL_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\nFor a local development install:\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-be\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"mcp-einvoicing-be\"],\n      \"cwd\": \"/path/to/mcp-einvoicing-be\"\n    }\n  }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration in:\n- **Global** (all projects): `~/.cursor/mcp.json`\n- **Project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-be\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-be\"],\n      \"env\": {\n        \"BCE_API_KEY\": \"your-bce-api-key\",\n        \"PEPPOL_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.\n\n## Kiro integration\n\nKiro supports MCP servers via its dedicated configuration file. Two levels are available:\n- **Global** (all projects): `~/.kiro/settings/mcp.json`\n- **Workspace** (this repository only): `.kiro/settings/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-be\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-be\"],\n      \"env\": {\n        \"BCE_API_KEY\": \"your-bce-api-key\",\n        \"PEPPOL_ENV\": \"production\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\nThe file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.\n\n> **Kiro security tip**: rather than writing secrets in plain text, use the syntax `\"BCE_API_KEY\": \"${BCE_API_KEY}\"`, Kiro resolves shell environment variables at startup.\n\n## Available tools\n\n### `validate_invoice_be`\n\nValidates a UBL 2.1 XML invoice. The `peppol-bis-3`/`pint-eu` profiles run real Schematron validation against the CEN EN 16931 base rules (~50 `BR-*` structural/arithmetic rules, via `mcp-einvoicing-core`'s bundled base Schematron — see CHANGELOG.md v0.8.0). This does not check the Peppol-specific overlay rules (no confirmed OpenPeppol redistribution rights); results carry an explicit `en16931-base-only` scope warning and should not be read as full Peppol BIS3 conformance. The `mercurius` profile runs the Mercurius-specific overlay (endpoint scheme, PO reference) but does not check base EN 16931/Peppol BIS 3.0 compliance.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml` | `string` | yes | Raw UBL 2.1 XML content |\n| `profile` | `string` | no | `peppol-bis-3` (default) or `mercurius` |\n\nReturns a `ValidationResult` with `valid`, `errors`, and `warnings` (each carrying the failed rule ID and a human-readable message).\n\n---\n\n### `generate_invoice_be`\n\nGenerates a valid UBL 2.1 Belgian e-invoice XML document from structured data.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice_data` | `object` | yes | Invoice fields (see `InvoiceInput` schema below) |\n| `profile` | `string` | no | `peppol-bis-3` (default) |\n\nThe `InvoiceInput` object supports:\n\n```json\n{\n  \"invoice_number\": \"INV-2024-001\",\n  \"issue_date\": \"2024-01-15\",\n  \"due_date\": \"2024-02-14\",\n  \"currency_code\": \"EUR\",\n  \"supplier\": { \"name\": \"...\", \"vat_number\": \"BE0428759497\", \"address\": {...} },\n  \"customer\": { \"name\": \"...\", \"vat_number\": \"BE0403170701\", \"address\": {...} },\n  \"lines\": [{ \"description\": \"...\", \"quantity\": 1, \"unit_price\": 100.00, \"vat_rate\": 21.0 }]\n}\n```\n\nReturns a UBL 2.1 XML string.\n\n---\n\n### `transform_to_ubl`\n\nConverts a structured JSON invoice payload to UBL 2.1 XML without full validation. Useful as a first step before validation.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `data` | `object` | yes | Source invoice data (same shape as `InvoiceInput`) |\n\n---\n\n### `lookup_vat_be`\n\nLooks up a Belgian enterprise number (VAT number) against the BCE/KBO public database.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `vat_number` | `string` | yes | Belgian VAT/enterprise number, e.g. `BE0428759497` or `0123456789` |\n\nReturns enterprise name, registered address, legal status, and NACE activity codes.\n\n---\n\n### Peppol network tools\n\nPeppol participant lookup, service-endpoint lookup, a DNS-only diagnostic, AS4 send, Peppol Directory search, and the OpenPeppol eDEC codelist tools are provided by the shared core Peppol tool plugin (`mcp_einvoicing_core.peppol.tools.register_peppol_tools`), mounted in `server.py` with a BE-specific identifier adapter: a bare Belgian VAT number (e.g. `0428759497` or `BE0428759497`) is normalized to the `0208:<digits>` Peppol scheme (KBO/BCE enterprise number); an already scheme-qualified identifier (e.g. `0208:0428759497`) passes through unchanged.\n\n`peppol_send` signs outbound messages with a real `wsse:Security` signature as of `mcp-einvoicing-core` v1.20.0 (previously computed and discarded — see CHANGELOG.md v0.10.0).\n\n| Tool | Description |\n|---|---|\n| `peppol_lookup_participant` | Check whether a business is registered on the Peppol network; returns registration status and supported document types |\n| `peppol_get_service_endpoint` | Fetch the AS4 endpoint for a participant's document type |\n| `resolve_peppol_dns` | DNS-only (SML) diagnostic, independent of SMP reachability |\n| `peppol_send` | Transmit a UBL/CII invoice via AS4 |\n| `peppol_directory_search` | Search the public Peppol Directory by participant, name, country, or document type |\n| `list_participant_id_schemes`, `list_document_type_ids`, `list_process_ids`, `list_spis_use_case_ids` | OpenPeppol eDEC codelist lookups (require `EINVOICING_PEPPOL_CODELIST_DIR`) |\n| `check_document_type_id_in_codelist`, `check_process_id_in_codelist`, `check_participant_id_scheme_in_codelist`, `get_peppol_codelist_version` | OpenPeppol eDEC codelist checks and version reporting |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n---\n\n### Peppol reporting and status tools\n\nAdded in v0.10.0 via three opt-in core plugins, mounted unconditionally in `server.py`. Each raises a clear error at call time (not at registration) if its extra or data directory is missing.\n\n| Tool | Plugin | Description |\n|---|---|---|\n| `validate_eusr_report` | `register_peppol_reporting_tools` | Validate an End User Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_tsr_report` | `register_peppol_reporting_tools` | Validate a Transaction Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_mls_message` | `register_peppol_mls_tools` | Validate a Message Level Status document (UBL `ApplicationResponse-2` subset). Requires the `[xslt2]` extra. |\n| `build_mls_message` | `register_peppol_mls_tools` | Build a document-level MLS response. Requires the `[xslt2]` extra. |\n| 13 `list_*`/`check_*` pairs, `get_en16931_codelist_version` | `register_en16931_codelist_tools` | EN 16931 semantic code list lookups/checks (units, VAT categories, etc.). Require `EINVOICING_EN16931_CODELIST_DIR`. |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n---\n\n### `parse_ubl_invoice_be`\n\nParses a UBL 2.1 XML invoice (Peppol BIS 3.0) into a structured dict. Satisfies the mandatory reception capability required by Art. 13quater of Royal Decree no. 1.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml_content` | `string` | yes | Raw UBL 2.1 XML invoice content |\n\nReturns `{\"success\": true, \"invoice\": {...}, \"warnings\": []}` on success, or `{\"success\": false, \"error\": \"...\"}` on parse failure.\n\n---\n\n### `get_invoice_types_be`\n\nReturns the list of supported Belgian e-invoice document types (invoice, credit note, debit note) with their UBL `customizationID` and `profileID` values for each profile.\n\nNo input parameters required.\n\n## B2G via Mercurius\n\nMercurius is the Belgian federal public-sector e-invoicing platform. It operates as a **Peppol network receiver**, not a separate API. B2G invoices are submitted through the standard Peppol network using the authority's participant ID in the `0208` scheme (KBO/BCE 10-digit enterprise number). The Access Point routes the invoice to Mercurius automatically. No Mercurius-specific submission endpoint or API key is required.\n\n## Architecture\n\n```\nmcp-einvoicing-be/\n├── src/\n│   └── mcp_einvoicing_be/\n│       ├── __init__.py\n│       ├── server.py              # MCP server entry point & tool registration\n│       ├── tools/\n│       │   ├── __init__.py\n│       │   ├── validation.py      # validate_invoice_be\n│       │   ├── generation.py      # generate_invoice_be\n│       │   ├── transformation.py  # transform_to_ubl\n│       │   ├── parsing.py         # parse_ubl_invoice_be\n│       │   └── lookup.py          # lookup_vat_be, get_invoice_types_be\n│       ├── models/\n│       │   ├── __init__.py\n│       │   ├── invoice.py         # InvoiceInput, InvoiceLine, ValidationResult\n│       │   └── party.py           # Supplier, Customer, Address\n│       ├── standards/\n│       │   ├── __init__.py\n│       │   ├── peppol_bis_3.py    # Peppol BIS Billing 3.0 rules & customization IDs\n│       │   ├── ubl.py             # UBL 2.1 namespace constants & XML helpers\n│       │   ├── pint_be.py         # PINT-BE placeholder (removed in v0.4.0)\n│       │   └── mercurius.py       # Mercurius network config & overlay rules\n│       └── utils/\n│           ├── __init__.py\n│           └── helpers.py         # VAT number normalization, date formatting, etc.\n├── tests/\n│   ├── __init__.py\n│   ├── conftest.py\n│   ├── test_tools/\n│   │   ├── __init__.py\n│   │   ├── test_validation.py\n│   │   ├── test_generation.py\n│   │   └── test_transformation.py\n│   └── fixtures/\n│       ├── invoice_valid_peppol.xml\n│       ├── invoice_valid_pint_be.xml\n│       └── invoice_invalid.xml\n├── .github/\n│   └── workflows/\n│       ├── ci.yml\n│       └── publish.yml\n├── pyproject.toml\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n└── LICENSE\n```\n\n### Relationship to `mcp-einvoicing-core`\n\n`mcp-einvoicing-core` provides:\n- Shared UBL 2.1/2.3 XML parsing and serialization utilities\n- EN 16931 base validation rules (syntax + semantic)\n- Peppol network client (SMP lookup, SML resolution)\n- Common Pydantic base models (`BaseInvoice`, `BaseParty`, `BaseValidationResult`)\n\n`mcp-einvoicing-be` adds Belgium-specific logic on top:\n- Mercurius network overlay rule validation (XPath-based) for B2G invoicing\n- BCE/KBO enterprise database integration\n- Belgian VAT number normalization (BTW/TVA format) and OGM/VCS check-digit validation\n- UBL 2.1 invoice parsing for mandatory reception (Art. 13quater)\n- `customizationID` and `profileID` values specific to the Belgian Peppol corner\n\n## Contributing\n\nContributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.\n\n```bash\ngit clone https://github.com/cmendezs/mcp-einvoicing-be.git\ncd mcp-einvoicing-be\nuv sync --all-extras\nuv run pytest\nuv run ruff check src tests\nuv run mypy src\n```\n\nAll pull requests must:\n- Pass the full test suite (`pytest`)\n- Pass linting (`ruff check`)\n- Pass type checking (`mypy`)\n- Include or update tests for any changed behaviour\n- Reference the relevant rule ID(s) when fixing a validation issue\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n\n## Other e-invoicing MCP servers\n\n| Country | Server |\n|---------|--------|\n| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |\n| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |\n| 🇧🇷 Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |\n| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |\n| 🇩🇪 Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |\n| 🇮🇳 India | [mcp-einvoicing-in](https://github.com/cmendezs/mcp-einvoicing-in) |\n| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| 🇲🇽 Mexico | [mcp-cfdi-mx](https://github.com/cmendezs/mcp-cfdi-mx) |\n| 🇵🇱 Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| 🇸🇬 Singapore | [mcp-invoicenow-sg](https://github.com/cmendezs/mcp-invoicenow-sg) |\n| 🇪🇸 Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n| 🇦🇪 United Arab Emirates | [mcp-einvoicing-ae](https://github.com/cmendezs/mcp-einvoicing-ae) |\n\n## License\n\nThis project is licensed under the **Apache 2.0** — see [LICENSE](LICENSE) for details. For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 15624,
  "sha": "3597f015724e77640285008fbe488bdc2d9eb5b3a8918e8ec0069548eb1df38d",
  "repo_slug": "cmendezs/mcp-einvoicing-be",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_einvoicing_be_969e626e/readme"
}