mcp-einvoicing-de

mcp-einvoicing-de 🇩🇪

英语 | 德语

用于 ZUGFeRD 2.x 和 XRechnung 3.x 格式（EN 16931、FeRD、KoSIT）德国电子发票的 Python MCP（Model Context Protocol）服务。它使 AI Agent（Claude、IDE）能够创建、验证、解析和转换电子发票，完全符合德国 B2B 电子发票强制要求（自 2025 年起生效，分阶段执行至 2027 年至 2028 年）以及欧洲标准 EN 16931。

---

简介

此软件包基于 mcp-einvoicing-core 构建，这是用于欧洲电子发票 MCP 服务的共享基础库。它提供共享模型、验证抽象、XML 实用工具和异常层级结构。

mcp-einvoicing-core 将作为传递依赖自动安装，无需额外步骤。

面向开发者： pip install -e ".[dev]" 会自动从 PyPI 安装基础软件包。

安装

通过 PyPI（推荐）

pip install mcp-einvoicing-de

无需预先安装，使用 uvx：

uvx mcp-einvoicing-de

从源代码安装

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

可选附加项

附加项	用途	安装
[xslt2]	用于 XSLT 2.0 Schematron 样式表的 Saxon-HE 后端（FeRD Factur-X 1.09.2 和 KoSIT XRechnung 3.0.2）。本地 Schematron 验证需要此项；lxml 仅支持 XSLT 1.0。	pip install mcp-einvoicing-de[xslt2]
[pdf]	用于提取嵌入式 XML 的额外 PDF 实用工具（pikepdf 也是生成 PDF/A-3 的基础依赖）。	pip install mcp-einvoicing-de[pdf]
[pymupdf]	替代 PDF 引擎（使用 PyMuPDF）。	pip install mcp-einvoicing-de[pymupdf]
[dev]	开发工具（pytest、ruff、pre-commit）。	pip install mcp-einvoicing-de[dev]

配置

此服务不需要外部凭据。可用的环境变量：

变量	描述	默认值
EINVOICING_DE_LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	INFO
EINVOICING_DE_KOSIT_VALIDATOR_URL	可自托管的 KoSIT 验证工具 REST 端点的 URL。仅在启用云验证时使用——参见 EINVOICING_DE_KOSIT_ENABLE
EINVOICING_DE_KOSIT_ENABLE	设置为 1 可启用 KoSIT 云验证（validator.kosit.de 或自托管端点）。默认仅进行本地 Schematron 验证
EINVOICING_PEPPOL_CODELIST_DIR	本地目录，其中包含你自己的 OpenPeppol eDEC 代码列表副本；Peppol 代码列表工具需要此目录（此软件包不包含这些文件；参见 mcp-einvoicing-core README）
EINVOICING_EN16931_CODELIST_DIR	本地目录，其中包含你自己的 CEF “Digital Building Blocks” EN 16931 语义代码列表副本；EN 16931 代码列表工具需要此目录（不包含在软件包中；参见 mcp-einvoicing-core README）

EUSR/TSR 报告和 MLS 工具还需要 [xslt2] 附加项以进行 Schematron 验证。

Claude Desktop 集成

将以下条目添加到 claude_desktop_config.json。无需设置环境变量：

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

Cursor 集成

Cursor 支持通过 stdio 使用 MCP 服务。将配置添加到：

• 全局（所有项目）：~/.cursor/mcp.json
• 项目（仅此代码库）：.cursor/mcp.json

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。有两个级别可供选择：

• 全局（所有项目）：~/.kiro/settings/mcp.json
• 工作区（仅此仓库）：.kiro/settings/mcp.json

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

保存后，文件会自动重新加载。你也可以通过命令面板（Cmd+Shift+P / Ctrl+Shift+P）打开配置，然后选择 MCP。

可用工具

工具	描述
invoice_create	生成 ZUGFeRD 或 XRechnung XML（CII 或 UBL）。强制执行 §14 Abs. 2 UStG 的 B2B 规定：对于 VAT 买方标识以 DE 开头的情况，除非设置了 transitional_period_opt_in=True，否则会拒绝非 XML 输出。output_format='pdf' 会生成 PDF/A-3 level B 混合发票，其中包含 sRGB ICC 配置文件、OutputIntent、嵌入式字体和确定性 /ID。
invoice_validate	根据 EN 16931 和 KoSIT 规则（BR-DE-*）验证发票。默认运行本地 Schematron 验证（数据不会离开你的计算机）；设置 cloud_validate=True 或 EINVOICING_DE_KOSIT_ENABLE=1，即可选择启用 KoSIT 云验证（validator.kosit.de 或可自托管的端点），并采用指数退避重试（1s/2s/4s）。本地 XSLT 2.0 验证需要 [xslt2] 扩展。
invoice_parse	从 ZUGFeRD 或 XRechnung XML，或嵌入了 factur-x.xml / zugferd-invoice.xml 的 PDF/A-3 混合发票中提取结构化数据。
invoice_convert	在不同 ZUGFeRD 配置文件之间转换、切换 ZUGFeRD/XRechnung CII 标头，或通过核心 convert_wire_format 执行 CII/UBL 跨语法转换。
datev_export	将 ZUGFeRD 发票导出为 DATEV EXTF 700 Buchungsstapel CSV 文件，以便导入 DATEV 会计软件。默认使用 SKR 03 科目（8400 收入 / 10000 应收款）。
tax_rules	查询德国 VAT 规则（税率、§13b UStG 反向征税代码、§19 UStG 小型企业阈值，以 JStG 2024 数值为准：上一年度 €25,000 / 本年度 €100,000，以及免税规定）。

Peppol 网络工具

参与方查询、服务端点查询、仅 DNS 诊断、AS4 发送、Peppol Directory 搜索，以及 OpenPeppol eDEC 代码列表工具由共享核心 Peppol 工具插件（mcp_einvoicing_core.peppol.tools.register_peppol_tools）提供，并在 server.py 中挂载了德国专用标识符适配器：不带方案的 USt-IdNr（例如 123456789 或 DE123456789）会规范化为 9930:<value> Peppol 方案（DE:VAT）；已包含方案的标识符（例如 9930:DE123456789，或用于通过 Leitweg-ID 路由的 B2G 发票的 0204:<leitweg-id>）则保持不变。若要通过 AS4 发送，请先使用 invoice_convert 生成 XRechnung UBL（或使用 invoice_create 并设置 target_syntax='UBL'），然后将结果传递给 peppol_send。

从 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。

使用示例

示例 1：验证发票

1. invoice_validate(
     xml_base64="...",   # Base64-encoded ZUGFeRD XML
     strict=True
   )
   → {
       "is_valid": true,
       "profile": "EN_16931",
       "syntax": "CII",
       "error_count": 0,
       "warning_count": 2,
       "errors": [],
       "warnings": [...],
       "validator_used": "local_schematron"
     }

示例 2：查询德国税务规则

2. tax_rules(query="reverse_charge", context="Bauleistungen")
   → {
       "results": [
         {
           "paragraph": "§13b Abs. 2 Nr. 5 UStG",
           "description_en": "Construction services (building contractor rule)",
           "vatex_code": "VATEX-EU-AE",
           "invoice_note": "Steuerschuldnerschaft des Leistungsempfängers (§13b UStG)"
         }
       ],
       "legal_disclaimer": "..."
     }

示例 3：检查 Peppol 注册状态

3. peppol_lookup_participant(
     identifier="123456789",   # bare USt-IdNr, normalized to 9930:DE123456789
     environment="production"
   )
   → {
       "is_registered": true,
       "participant_id": "9930:DE123456789",
       "supported_document_types": ["urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"],
       "smp_hostname": "b-...iso6523-actorid-upis.edelivery.tech.ec.europa.eu"
     }

示例 4：解析发票数据

4. invoice_parse(xml_base64="...", include_raw_xml=False)
   → {
       "profile": "XRECHNUNG",
       "syntax": "CII",
       "invoice_number": "RE-2025-001",
       "invoice_date": "2025-01-15",
       "seller_name": "Muster GmbH",
       "buyer_name": "Käufer AG",
       "tax_inclusive_amount": "119.00",
       "currency_code": "EUR"
     }

架构

mcp-einvoicing-de (this package, standalone MCP server)
├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic models (all profiles)
├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* rules
├── KoSITValidator                     ← Remote validation tool (optional)
└── Tools: create / validate / parse / convert / datev_export / tax_rules
    (+ core Peppol tool plugin, mounted separately: lookup / send / DNS / codelists)

        ↑ extends
mcp-einvoicing-core (shared base, installed as dependency)
├── BaseDocumentGenerator / Validator / Parser
├── BaseInvoice, BaseParty … (Pydantic)
├── xml_utils, exceptions
└── EInvoicingMCPServer

厂商中立性

此服务本身实现了该标准：它会在本地构建、验证并签署文档。它不是商业发票平台的客户端，你的签名密钥和凭据绝不会离开自己的基础设施。

Peppol 接入点是可选的：通过 peppol_send 传输是可用渠道之一，任何经认可的接入点都使用相同的 AS4 配置文件，因此更换服务提供商只需更改配置，无须更改代码。此软件包不支持直接向德国 B2G 州级门户（ZRE/OZG-RE）提交。

支持的标准

标准	版本	配置文件 / 语法
ZUGFeRD	2.5.2	MINIMUM、BASIC WL、BASIC、EN 16931、EXTENDED
XRechnung	3.0.2	CII（跨行业发票）、UBL（通用商业语言）
KoSIT xrechnung-schematron 规则集	2.6.0	XRechnung 3.0.2 的验证规则（与规范本身采用不同的版本序列）
EN 16931	2017	电子发票欧洲核心数据模型
Peppol BIS	3.0	Billing 3.0（符合 EN 16931）

注意： ZUGFeRD 2.x 和 XRechnung 3.x 在 EN 16931 配置文件层面共享相同的 CII XML 语法。因此，两种格式之间可以无损转换。EXTENDED 配置文件是 ZUGFeRD 专有的，在 XRechnung 中没有对应项。

资源	链接
FeRD ZUGFeRD 规范	ferd-net.de
KoSIT XRechnung	xeinkauf.de
KoSIT 验证工具	github.com/itplr-kosit/validationtool
EN 16931-1:2017	CEN
Peppol BIS Billing 3.0	docs.peppol.eu

测试

# Install development dependencies
pip install -e ".[dev]"

# Run the full test suite
pytest tests/ -v

# With coverage report
pytest --cov=mcp_einvoicing_de --cov-report=term-missing

# Model tests only
pytest tests/test_models.py -v

贡献

欢迎贡献。对于较大的改动，请在提交拉取请求前先创建 issue。

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make audit

其他电子发票 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 许可。详情请参阅 LICENSE 文件。完整的版本历史请参阅 CHANGELOG.md。