mcp-einvoicing-be

mcp-einvoicing-be 🇧🇪

English | Francais | Nederlands

---

简介

mcp-einvoicing-be 是一个 MCP（模型上下文协议） 服务，提供比利时电子发票工具。它涵盖比利时电子发票生态系统的全部内容：Peppol BIS Billing 3.0、UBL 2.1，以及用于公共部门发票的 Mercurius 网络。该服务属于按国家/地区划分的 mcp-einvoicing-* 服务系列，均基于 mcp-einvoicing-core 构建，后者提供共享的验证引擎、UBL 抽象和 Peppol 网络实用工具。

安装

要求

• 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 代码列表副本；代码列表工具需要该副本（此软件包不附带；请参阅 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 工具还需要 [xslt2] extra（pip install "mcp-einvoicing-be[xslt2]"）以进行 Schematron 验证。

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 服务。提供两个级别：

• 全局（所有项目）：~/.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 会在启动时解析 shell 环境变量。

可用工具

validate_invoice_be

验证 UBL 2.1 XML 发票。peppol-bis-3/pint-eu 配置文件会针对 CEN EN 16931 基础规则运行真实的 Schematron 验证（约 50 条 BR-* 结构/算术规则，通过 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

返回一个 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 活动代码。

---

Peppol 网络工具

参与方查询、服务端点查询、仅 DNS 诊断、AS4 发送、Peppol Directory 搜索，以及 OpenPeppol eDEC 代码列表工具均由共享核心 Peppol 工具插件（mcp_einvoicing_core.peppol.tools.register_peppol_tools）提供，并在 server.py 中挂载了比利时专用标识符适配器：纯比利时增值税号（例如 0428759497 或 BE0428759497）会规范化为 0208:<digits> Peppol 方案（KBO/BCE 企业编号）；已带方案的标识符（例如 0208:0428759497）则保持不变。

自 mcp-einvoicing-core v1.20.0 起，peppol_send 会使用真实的 wsse:Security 签名对出站消息签名（此前会计算签名但将其丢弃——参见 CHANGELOG.md v0.10.0）。

工具	描述
peppol_lookup_participant	检查企业是否已在 Peppol 网络注册；返回注册状态和受支持的文档类型
peppol_get_service_endpoint	获取参与方对应文档类型的 AS4 端点
resolve_peppol_dns	仅 DNS（SML）诊断，不受 SMP 可达性影响
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 中通过三个可选的核心插件添加，并在 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 语义代码表（单位、增值税类别等）。需要 EINVOICING_EN16931_CODELIST_DIR。

有关这些工具的完整参数文档，请参阅 mcp-einvoicing-core README。

---

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, 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 企业数据库集成
• 比利时增值税号规范化（BTW/TVA 格式）以及 OGM/VCS 校验位验证
• 满足强制接收要求的 UBL 2.1 发票解析（第 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）
• 通过 lint 检查（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。