Skip to main content
Glama
mcp-einvoicing-de

mcp-einvoicing-de

mcp-einvoicing-de 🇩🇪

License PyPI version Python mcp-einvoicing-de MCP server

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

pip install mcp-einvoicing-de

Without prior installation using uvx:

uvx mcp-einvoicing-de

From 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

EINVOICING_DE_LOG_LEVEL

Logging level (DEBUG, INFO, WARNING, ERROR)

INFO

EINVOICING_DE_KOSIT_VALIDATOR_URL

URL of the KoSIT validation tool (optional, for remote validation)

—

EINVOICING_DE_PEPPOL_SMP_URL

Peppol-SMP lookup URL (optional)

—

EINVOICING_DE_PDF_ENGINE

PDF generation module (reportlab or pymupdf)

reportlab

🤖 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

invoice_create

Create ZUGFeRD or XRechnung XML (CII or UBL); PDF/A-3 hybrid planned (v0.2.0)

invoice_validate

Validate invoice against EN 16931 and KoSIT Schematron rules (BR-DE-*)

invoice_parse

Extract structured data from an existing ZUGFeRD or XRechnung file

invoice_convert

Convert between ZUGFeRD profiles or ZUGFeRD ↔ XRechnung

peppol_check

Check Peppol participant registration of a German company (AS4)

tax_rules

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

ferd-net.de

KoSIT XRechnung

xeinkauf.de

KoSIT validation tool

github.com/itplr-kosit/validationtool

EN 16931-1:2017

CEN

Peppol BIS Billing 3.0

docs.peppol.eu


🧪 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 -v

Roadmap

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 reportlab / PyMuPDF

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 audit

Other e-invoicing MCP servers

Country

Server

🌍 Global

mcp-einvoicing-core

🇧🇪 Belgium

mcp-einvoicing-be

🇫🇷 France

mcp-facture-electronique-fr

🇮🇹 Italy

mcp-fattura-elettronica-it

🇩🇪 Germany

mcp-einvoicing-de


📄 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 tools
build_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_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

    A3.6/5.0

    Scored across 50 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      6
      50 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      34
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      43
      93 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model 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.
      50
      297 PyPI
      Apache 2.0