mcp-einvoicing-de
This server handles the full lifecycle of German electronic invoices (ZUGFeRD 2.x and XRechnung 3.x), compliant with EN 16931 and German B2B e-invoicing mandates.
Create Invoices (
invoice_create): Generate ZUGFeRD or XRechnung invoices in CII or UBL XML format, supporting all ZUGFeRD profiles (MINIMUM, BASIC_WL, BASIC, EN_16931, EXTENDED) and XRechnung 3.x.Validate Invoices (
invoice_validate): Validate invoice XML against EN 16931 rules and German KoSIT Schematron business rules (BR-DE-*), with auto-detection of profile/syntax, optional strict mode, and optional remote KoSIT validator integration.Parse Invoices (
invoice_parse): Extract structured JSON data from ZUGFeRD or XRechnung files provided as raw XML, base64-encoded XML, or base64-encoded PDF (ZUGFeRD hybrid PDF/A-3).Convert Invoices (
invoice_convert): Convert between ZUGFeRD profiles (upgrades/downgrades), between ZUGFeRD and XRechnung, and between CII and UBL syntax (XRechnung only).Check Peppol Registration (
peppol_check): Verify if a German company is registered on the Peppol network via live DNS + SMP lookup, returning registration status, supported document types, and AS4 endpoint URL.Query German VAT Rules (
tax_rules): Look up VAT rates (19%, 7%), VAT category codes, reverse charge rules (§13b UStG), zero-rate/exemption provisions (§4 UStG), intra-community supply rules, and VATEX exemption reason codes.
mcp-einvoicing-de 🇩🇪
MCP (Model Context Protocol) server in Python for German electronic invoicing in ZUGFeRD 2.x and XRechnung 3.x formats (EN 16931, FeRD, KoSIT). Enables AI agents (Claude, IDEs) to create, validate, parse, and convert e-invoices that fully comply with the German B2B e-invoicing mandate (valid from 2025, phased enforcement until 2027–2028) and the European standard EN 16931.
English summary
This is a Model Context Protocol (MCP) server for German electronic invoicing. It exposes 6 tools covering the full lifecycle of a ZUGFeRD or XRechnung invoice: creation (CII/UBL XML), validation against EN 16931 and KoSIT Schematron rules (BR-DE-*), parsing of existing invoice files, profile and syntax conversion, Peppol participant registration lookup (AS4), and German VAT rules (Steuerklassen, §13b UStG reverse charge, exemptions). Supports all ZUGFeRD 2.x profiles (MINIMUM through EXTENDED) and XRechnung 3.x (CII and UBL syntax). Licensed under Apache 2.0.
Related MCP server: mcp-facture-electronique-fr
Built upon
This package is based on mcp-einvoicing-core, a shared base library for European e-invoicing MCP servers. It provides common models, validation abstractions, XML helper functions, and the exception hierarchy.
mcp-einvoicing-core is automatically installed as a transitive dependency — no additional step required.
For developers:
pip install -e ".[dev]"automatically installs the base package from PyPI.
🏗️ Architecture
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🚀 Installation
Via PyPI (recommended)
pip install mcp-einvoicing-deWithout prior installation using uvx:
uvx mcp-einvoicing-deFrom source
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]"⚙️ Configuration
The server does not require external credentials in v0.1.0. Available environment variables:
Variable | Description | Default |
| Logging level ( |
|
| URL of the KoSIT validation tool (optional, for remote validation) | — |
| Peppol-SMP lookup URL (optional) | — |
| PDF generation module ( |
|
🤖 Claude Desktop integration
Entry in the claude_desktop_config.json file:
{
"mcpServers": {
"einvoicing-de": {
"command": "uvx",
"args": ["mcp-einvoicing-de"]
}
}
}⌨️ Cursor integration
Configuration file (~/.cursor/mcp.json or .cursor/mcp.json in the project directory):
{
"mcpServers": {
"einvoicing-de": {
"command": "uvx",
"args": ["mcp-einvoicing-de"]
}
}
}🪐 Kiro integration
{
"mcpServers": {
"einvoicing-de": {
"command": "uvx",
"args": ["mcp-einvoicing-de"],
"disabled": false,
"autoApprove": []
}
}
}🧰 Available MCP tools
Tool | Description |
| Create ZUGFeRD or XRechnung XML (CII or UBL); PDF/A-3 hybrid planned (v0.2.0) |
| Validate invoice against EN 16931 and KoSIT Schematron rules (BR-DE-*) |
| Extract structured data from an existing ZUGFeRD or XRechnung file |
| Convert between ZUGFeRD profiles or ZUGFeRD ↔ XRechnung |
| Check Peppol participant registration of a German company (AS4) |
| Query German VAT rules (tax classes, §13b UStG, exemptions) |
Usage examples
Example 1 — Validate invoice
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"
}Example 2 — Query German tax rules
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": "..."
}Example 3 — Check Peppol registration
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"
}Example 4 — Parse invoice data
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"
}📚 Supported standards
Standard | Version | Profiles / Syntax |
ZUGFeRD | 2.3 | MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED |
XRechnung | 3.x | CII (Cross Industry Invoice), UBL (Universal Business Language) |
EN 16931 | — | European core data model for electronic invoicing |
Peppol BIS | 3.0 | Billing 3.0 (DE PINT) |
Note: ZUGFeRD 2.x and XRechnung 3.x share the same CII XML syntax at the EN 16931 profile level. Conversion between both formats is therefore possible without data loss. The EXTENDED profile is ZUGFeRD-specific and has no XRechnung equivalent.
Resource | Link |
FeRD ZUGFeRD specification | |
KoSIT XRechnung | |
KoSIT validation tool | |
EN 16931-1:2017 | |
Peppol BIS Billing 3.0 |
🧪 Tests
# 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 -vRoadmap
Version | Features |
v0.1.0 (current) | Tools: create, validate, parse, convert, peppol_check, tax_rules |
v0.2.0 | PDF/A-3 embedding (ZUGFeRD hybrid) via |
v0.3.0 | KoSIT online validator fully integrated |
v0.4.0 | Peppol AS4 direct transmission |
v0.5.0 | DATEV export format |
v1.0.0 | Production-ready, full EN 16931 coverage |
Contributing
Contributions are welcome. Please open an issue before submitting a pull request for significant changes.
git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make auditOther e-invoicing MCP servers
Country | Server |
🌍 Global | |
🇧🇪 Belgium | |
🇫🇷 France | |
🇮🇹 Italy | |
🇩🇪 Germany |
📄 License
This project is licensed under the Apache-2.0 License. See the LICENSE file for details.
Copyright 2026 cmendezs
Project maintained by cmendezs. For questions regarding the implementation of the ZUGFeRD or XRechnung specification, please open an issue.
Available Tools
50 toolsbuild_mls_messageBuild 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_codeCheck Allowance Reason CodeA
Check whether code is a recognized allowance reason code.
Inputs: code (required). Returns: object
check_charge_reason_codeCheck Charge Reason CodeA
Check whether code is a recognized charge reason code.
Inputs: code (required). Returns: object
check_country_codeCheck Country CodeA
Check whether code is a recognized ISO 3166-1 alpha-2 country code.
Inputs: code (required). Returns: object
check_currency_codeCheck Currency CodeA
Check whether code is a recognized ISO 4217 currency code.
Inputs: code (required). Returns: object
check_document_name_codeCheck Document Name CodeA
Check whether code is a recognized UNCL1001 document name code.
Inputs: code (required). Returns: object
check_document_type_id_in_codelistCheck Document Type Id In CodelistA
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_codeCheck Eas CodeA
Check whether code is a recognized Electronic Address Scheme code.
Inputs: code (required). Returns: object
check_icd_codeCheck Icd CodeA
Check whether code is a recognized ISO 6523 ICD code.
Inputs: code (required). Returns: object
check_item_type_codeCheck Item Type CodeB
Check whether code is a recognized item type identification code.
Inputs: code (required). Returns: object
check_mime_codeCheck Mime CodeA
Check whether code is a recognized MIME type for embedded attachments.
Inputs: code (required). Returns: object
check_participant_id_scheme_in_codelistCheck 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_codeCheck Payment Means CodeA
Check whether code is a recognized UNCL4461 payment means code.
Inputs: code (required). Returns: object
check_process_id_in_codelistCheck Process Id In CodelistA
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_codeCheck Reference Qualifier CodeA
Check whether code is a recognized UNCL1153 reference qualifier code.
Inputs: code (required). Returns: object
check_vat_category_codeCheck Vat Category CodeA
Check whether code is a recognized UNCL5305 VAT category code.
Inputs: code (required). Returns: object
check_vatex_codeCheck Vatex CodeA
Check whether code is a recognized VATEX VAT exemption reason code.
Inputs: code (required). Returns: object
datev_exportDatev ExportA
Export a ZUGFeRD invoice to DATEV CSV format (EXTF 700, Buchungsstapel).
Produces a CSV file importable by DATEV Belegtransfer or DATEV Rechnungswesen. Maps invoice line items to DATEV booking records with configurable accounts.
Inputs: invoice (required), client_number, revenue_account, consultant_number, +2 more. Returns: object
get_en16931_codelist_versionGet En16931 Codelist VersionA
Report the CEF EN 16931 code-list release version(s) currently configured locally.
Inputs: no named parameters. Returns: object
get_peppol_codelist_versionGet Peppol Codelist VersionA
Report the OpenPeppol eDEC code list release version(s) currently configured locally.
Inputs: no named parameters. Returns: object
invoice_convertInvoice ConvertA
Convert a ZUGFeRD or XRechnung invoice to a different profile or syntax.
Supports ZUGFeRD profile upgrades and downgrades, ZUGFeRD <-> XRechnung conversion, and cross-syntax CII <-> UBL transformation. Profile downgrades may result in data loss; set allow_data_loss=True to permit this.
Inputs: target_profile (required), xml_base64, xml_content, target_syntax, +1 more. Returns: object
invoice_createInvoice CreateA
Generate a ZUGFeRD 2.x or XRechnung 3.x invoice in XML (CII or UBL) format.
Supports all ZUGFeRD profiles: MINIMUM, BASIC_WL, BASIC, EN_16931, EXTENDED. For XRechnung, set profile to XRECHNUNG and choose CII or UBL syntax. When the buyer is a German VAT-registered business (DE-prefixed VAT id), the Wachstumschancengesetz B2B mandate (effective 2025-01-01, §14 Abs. 2 UStG) requires a structured EN 16931 invoice. Non-XML output is rejected unless transitional_period_opt_in is set to True (allowed only 2025-2026 with the buyer's written consent).
Inputs: invoice (required), syntax, pretty_print, output_format, +1 more. Returns: object
invoice_parseInvoice ParseA
Extract structured data from a ZUGFeRD 2.x or XRechnung 3.x invoice.
Accepts raw XML (CII or UBL), base64-encoded XML, or base64-encoded PDF (ZUGFeRD hybrid — the XML is extracted from the PDF/A-3 attachment). Returns a structured JSON object matching the invoice data model.
Inputs: pdf_base64, xml_base64, xml_content, include_raw_xml. Returns: object
invoice_validateInvoice ValidateA
Validate a ZUGFeRD 2.x or XRechnung 3.x invoice XML.
Checks against EN 16931 rules and German KoSIT Schematron rules (BR-DE-* business rules). Returns a structured validation report with errors and warnings. Supports all ZUGFeRD profiles (MINIMUM through EXTENDED) and XRechnung (CII and UBL syntax). Profile and syntax are auto-detected if not specified. By default this validator runs entirely locally (Schematron only). Set cloud_validate=True (or EINVOICING_DE_KOSIT_ENABLE=1) to opt in to sending the invoice XML to a remote KoSIT endpoint. Doing so egresses the full invoice payload.
Inputs: strict, syntax, profile, xml_base64, +4 more. Returns: object
list_allowance_reason_codesList Allowance Reason CodesA
List allowance reason codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_charge_reason_codesList Charge Reason CodesA
List charge reason codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_country_codesList 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_codesList Currency CodesA
List ISO 4217 currency codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_document_name_codesList Document Name CodesA
List UNCL1001 document name codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_document_type_idsList 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_codesList Eas CodesA
List Electronic Address Scheme (EAS) codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_icd_codesList Icd CodesA
List ISO 6523 ICD codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_item_type_codesList Item Type CodesA
List item type identification codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_mime_codesList Mime CodesB
List recognized MIME types for embedded attachments.
Inputs: no named parameters. Returns: object
list_participant_id_schemesList 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_codesList Payment Means CodesA
List UNCL4461 payment means codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_process_idsList 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_codesList 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_idsList 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_codesList Vat Category CodesA
List UNCL5305 VAT category codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
list_vatex_codesList Vatex CodesA
List VATEX (VAT exemption reason) codes from the CEF EN 16931 code list.
Inputs: no named parameters. Returns: object
peppol_directory_searchPeppol Directory SearchA
Search the Peppol Directory for registered participants.
Public, unauthenticated search (no relation to SMP lookup). At least one of q/participant/name/country/doctype must be supplied.
Inputs: q, name, country, doctype, +4 more. Returns: object
peppol_get_service_endpointPeppol 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_participantPeppol 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_sendPeppol 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_dnsResolve 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
tax_rulesTax RulesA
Query German VAT rules for e-invoicing.
Returns structured information about VAT rates (19%, 7%), VAT category codes, reverse charge rules under §13b UStG, zero-rate and exemption provisions (§4 UStG), intra-community supply rules, and VATEX exemption reason codes. For use when building invoice creation logic or validating VAT treatment.
Inputs: query (required), context. Returns: object
validate_eusr_reportValidate 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_mls_messageValidate 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_reportValidate 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
Scored across 50 tools
The tool set has many code list checking tools that follow a clear pattern (list_X_codes/check_X_code), which are distinct from the invoice processing tools. However, there are repeated tools (e.g., list_eas_codes appears twice in the provided list) and some closely related validation tools (TSR vs MLS vs EUSR) that could cause confusion.
Most tools follow consistent verb_noun patterns: check_, list_, get_, create_, validate_. There are minor deviations like `peppol_lookup_participant` and `resolve_peppol_dns` using different prefixes, but overall the naming is predictable and clear.
50+ tools is excessive, largely driven by repetitive list_x_codes/check_x_code pairs for each codelist. The core invoice functionality is only ~5 tools, while code-list helpers dominate the surface.
The invoice lifecycle is well covered with create/validate/convert/export, and Peppol lookup/send tools cover the main delivery flow. Missing operations like cancel or fetch invoice history are minor for the domain scope.
Maintenance
Related MCP Connectors
Validate, parse, fix and render e-invoices: XRechnung, ZUGFeRD, Peppol, KSeF, Facturae, MyInvois
Create ZUGFeRD e-invoices from JSON or PDF, verify Factur-X, check VAT IDs and Peppol.
Validate XRechnung, ZUGFeRD and Factur-X with the KoSIT validator and create valid e-invoices.
Create and validate XRechnung, ZUGFeRD and Peppol e-invoices (KoSIT); Peppol lookup, rule help.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP 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.650 npm2MIT
- AlicenseAqualityBmaintenanceModel 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.341Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Italian Electronic Invoicing (FatturaPA / SDI). Provide tools to validate, generate, and explore API specifications for Sistema di Interscambio (SDI) interoperability.4393 PyPI2Apache 2.0
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Belgian Electronic Invoicing (Peppol BIS 3.0 / PINT-BE / Mercurius). Provides tools to validate, generate, and transform UBL 2.1 e-invoices, and look up BCE/KBO enterprise data and Peppol participants.50297 PyPIApache 2.0