mcp-einvoicing-de 🇩🇪

English | Deutsch

MCP server (Model Context Protocol) 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 are fully compliant with the German B2B e-invoicing mandate (effective from 2025, phased enforcement through 2027 to 2028) and the European standard EN 16931.

🏗️ Built on

This package is built on mcp-einvoicing-core, a shared base library for European e-invoicing MCP servers. It provides shared models, validation abstractions, XML utilities, and the exception hierarchy.

mcp-einvoicing-core is automatically installed as a transitive dependency, no additional step required.

For developers: pip install -e ".[dev]" installs the base package automatically from PyPI.

🏗️ Architecture

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

🚀 Installation

Via PyPI (recommended)

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

Optional extras

⚙️ Configuration

The server does not require external credentials. Available environment variables:

🤖 Claude Desktop integration

Add the following entry to claude_desktop_config.json:

{
  "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

Peppol network tools

Peppol participant lookup, service-endpoint lookup, a DNS-only diagnostic, AS4 send, and the OpenPeppol eDEC codelist tools are provided by the shared core Peppol tool plugin (mcp_einvoicing_core.peppol.tools.register_peppol_tools), mounted in server.py with a German-specific identifier adapter: a bare USt-IdNr (e.g. 123456789 or DE123456789) is normalized to the 9930:<value> Peppol scheme (DE:VAT); an already scheme-qualified identifier (e.g. 9930:DE123456789, or 0204:<leitweg-id> for Leitweg-ID-routed B2G invoices) passes through unchanged. To send via AS4, first produce XRechnung UBL with invoice_convert (or invoice_create with target_syntax='UBL'), then pass the result to peppol_send.

See the mcp-einvoicing-core README for full parameter documentation on these tools.

Usage examples

Example 1: Validate an invoice

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

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_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"
     }

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

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 specific to ZUGFeRD and has no XRechnung equivalent.

🧪 Tests

# 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

Roadmap

Current version: v0.8.0.

For the history of past releases, see RELEASE.md.

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

📄 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 about the ZUGFeRD or XRechnung specification implementation, please open an issue.