mcp-einvoicing-de 🇩🇪

Name: mcp-einvoicing-de
Author: cmendezs

License PyPI version Python mcp-einvoicing-de MCP server

这是一个基于 Python 的模型上下文协议（MCP）服务器，用于处理德国电子发票，支持 ZUGFeRD 2.x 和 XRechnung 3.x 格式（符合 EN 16931、FeRD、KoSIT 标准）。它使 AI 代理（如 Claude、IDE）能够创建、验证、解析和转换完全符合德国 B2B 电子发票授权（2025 年生效，2027-2028 年逐步强制执行）以及欧洲标准 EN 16931 的电子发票。

英文摘要

这是一个用于德国电子发票的模型上下文协议 (MCP) 服务器。它提供了 6 个工具，涵盖了 ZUGFeRD 或 XRechnung 发票的完整生命周期：创建（CII/UBL XML）、根据 EN 16931 和 KoSIT Schematron 规则（BR-DE-*）进行验证、解析现有发票文件、配置文件和语法转换、Peppol 参与者注册查询（AS4）以及德国增值税规则（税率等级、§13b UStG 反向征税、豁免）。支持所有 ZUGFeRD 2.x 配置文件（从 MINIMUM 到 EXTENDED）和 XRechnung 3.x（CII 和 UBL 语法）。采用 Apache 2.0 许可协议。

构建基础

该软件包基于 mcp-einvoicing-core，这是一个用于欧洲电子发票 MCP 服务器的通用基础库。它提供了通用模型、验证抽象、XML 辅助函数和异常层次结构。

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

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

🏗️ 架构

mcp-einvoicing-de (dieses Paket — eigenständiger MCP-Server)
├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic-Modelle (alle Profile)
├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* Regeln
├── KoSITValidator                     ← Remote-Validierungstool (optional)
└── Tools: create / validate / parse / convert / peppol_check / tax_rules

        ↑ erweitert
mcp-einvoicing-core (gemeinsame Basis, als Abhängigkeit installiert)
├── BaseDocumentGenerator / Validator / Parser
├── BaseInvoice, BaseParty … (Pydantic)
├── xml_utils, exceptions
└── EInvoicingMCPServer

🚀 安装

通过 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]"

⚙️ 配置

该服务器在 v0.1.0 版本中不需要外部凭据。可用的环境变量：

变量	描述	默认值
`EINVOICING_DE_LOG_LEVEL`	日志级别 (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`EINVOICING_DE_KOSIT_VALIDATOR_URL`	KoSIT 验证工具的 URL（可选，用于远程验证）	—
`EINVOICING_DE_PEPPOL_SMP_URL`	Peppol-SMP 查询 URL（可选）	—
`EINVOICING_DE_PDF_ENGINE`	PDF 生成引擎 (`reportlab` 或 `pymupdf`)	`reportlab`

🤖 Claude Desktop 集成

在 claude_desktop_config.json 文件中添加条目：

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

⌨️ Cursor 集成

配置文件（~/.cursor/mcp.json 或项目目录下的 .cursor/mcp.json）：

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

🪐 Kiro 集成

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

🧰 可用的 MCP 工具

工具	描述
`invoice_create`	生成 ZUGFeRD 或 XRechnung XML（CII 或 UBL）；计划支持 PDF/A-3 混合格式 (v0.2.0)
`invoice_validate`	根据 EN 16931 和 KoSIT-Schematron 规则 (BR-DE-*) 检查发票
`invoice_parse`	从现有的 ZUGFeRD 或 XRechnung 文件中提取结构化数据
`invoice_convert`	在 ZUGFeRD 配置文件之间或 ZUGFeRD ↔ XRechnung 之间进行转换
`peppol_check`	检查德国公司的 Peppol 参与者注册情况 (AS4)
`tax_rules`	查询德国增值税规则（税率等级、§13b UStG、豁免）

使用示例

示例 1 — 验证发票

1. invoice_validate(
     xml_base64="...",   # Base64-kodiertes 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_check(
     participant_id="0204:991-1234512345-06",
     environment="production"
   )
   → {
       "is_registered": true,
       "participant_id": "0204:991-1234512345-06",
       "document_type_supported": true,
       "access_point_url": "https://ap.example.de/as4",
       "transport_profile": "peppol-transport-as4-v2.0"
     }

示例 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"
     }

📚 支持的标准

标准	版本	配置文件 / 语法
ZUGFeRD	2.3	MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
XRechnung	3.x	CII (Cross Industry Invoice), UBL (Universal Business Language)
EN 16931	—	欧洲电子发票核心数据模型
Peppol BIS	3.0	Billing 3.0 (DE PINT)

注意： 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

🧪 测试

# Entwicklungsabhängigkeiten installieren
pip install -e ".[dev]"

# Gesamte Testsuite ausführen
pytest tests/ -v

# Mit Abdeckungsbericht
pytest --cov=mcp_einvoicing_de --cov-report=term-missing

# Nur Modell-Tests
pytest tests/test_models.py -v

开发路线图

版本	功能
v0.1.0 (当前)	工具：create, validate, parse, convert, peppol_check, tax_rules
v0.2.0	通过 `reportlab` / `PyMuPDF` 实现 PDF/A-3 嵌入 (ZUGFeRD 混合格式)
v0.3.0	完全集成 KoSIT 在线验证器
v0.4.0	Peppol AS4 直接传输
v0.5.0	DATEV 导出格式
v1.0.0	生产就绪，完全覆盖 EN 16931

贡献

欢迎贡献。在提交重大更改的 Pull Request 之前，请先开启一个 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-facture-electronique-fr
🇮🇹 意大利	mcp-fattura-elettronica-it
🇩🇪 德国	mcp-einvoicing-de

📄 许可协议

本项目采用 Apache-2.0 许可协议。详情请参阅 LICENSE 文件。

项目由 cmendezs 维护。如有关于 ZUGFeRD 或 XRechnung 规范实现的问题，请开启一个 Issue。

mcp-einvoicing-de