{
  "markdown": "# mcp-einvoicing-de 🇩🇪\n\n[English](README.md) | [Deutsch](README.de.md)\n\n<!-- mcp-name: io.github.cmendezs/mcp-einvoicing-de -->\n\n![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-einvoicing-de.svg)](https://pypi.org/project/mcp-einvoicing-de/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-einvoicing-de.svg)](https://pypi.org/project/mcp-einvoicing-de/)\n[![mcp-einvoicing-de MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-de/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-de)\n\nMCP 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.\n\n---\n\n## Introduction\n\nThis package is built on [**mcp-einvoicing-core**](https://github.com/cmendezs/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.\n\n`mcp-einvoicing-core` is automatically installed as a transitive dependency, no additional step required.\n\n> **For developers:** `pip install -e \".[dev]\"` installs the base package automatically from PyPI.\n\n## Installation\n\n### Via PyPI (recommended)\n\n```bash\npip install mcp-einvoicing-de\n```\n\nWithout prior installation, using `uvx`:\n\n```bash\nuvx mcp-einvoicing-de\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cmendezs/mcp-einvoicing-de.git\ncd mcp-einvoicing-de\n\npython -m venv .venv\nsource .venv/bin/activate   # Windows: .venv\\Scripts\\activate\n\npip install -e \".[dev]\"\n```\n\n### Optional extras\n\n| Extra | Purpose | Install |\n|-------|---------|---------|\n| `[xslt2]` | Saxon-HE backend for XSLT 2.0 Schematron stylesheets (FeRD Factur-X 1.09.2 and KoSIT XRechnung 3.0.2). Required for local Schematron validation; lxml supports XSLT 1.0 only. | `pip install mcp-einvoicing-de[xslt2]` |\n| `[pdf]` | Additional PDF utilities for embedded XML extraction (`pikepdf` is also a base dependency for PDF/A-3 generation). | `pip install mcp-einvoicing-de[pdf]` |\n| `[pymupdf]` | Alternative PDF engine (uses `PyMuPDF`). | `pip install mcp-einvoicing-de[pymupdf]` |\n| `[dev]` | Development tools (pytest, ruff, pre-commit). | `pip install mcp-einvoicing-de[dev]` |\n\n## Configuration\n\nThe server does not require external credentials. Available environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `EINVOICING_DE_LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |\n| `EINVOICING_DE_KOSIT_VALIDATOR_URL` | URL of a self-hosted KoSIT validation tool REST endpoint. Only used if cloud validation is enabled — see `EINVOICING_DE_KOSIT_ENABLE` | |\n| `EINVOICING_DE_KOSIT_ENABLE` | Set to `1` to enable KoSIT cloud validation (`validator.kosit.de` or a self-hosted endpoint). Local Schematron-only validation is the default | |\n| `EINVOICING_PEPPOL_CODELIST_DIR` | Local directory containing your own copy of the OpenPeppol eDEC Code Lists, required by the Peppol codelist tools (not bundled with this package; see `mcp-einvoicing-core` README) | |\n| `EINVOICING_EN16931_CODELIST_DIR` | Local directory containing your own copy of the CEF \"Digital Building Blocks\" EN 16931 semantic code lists, required by the EN 16931 codelist tools (not bundled; see `mcp-einvoicing-core` README) | |\n\nThe EUSR/TSR reporting and MLS tools additionally require the `[xslt2]` extra for Schematron validation.\n\n## Claude Desktop integration\n\nAdd the following entry to `claude_desktop_config.json`. No environment variables are required:\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-de\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-de\"]\n    }\n  }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration in:\n- **Global** (all projects): `~/.cursor/mcp.json`\n- **Project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-de\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-de\"]\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.\n\n## Kiro integration\n\nKiro supports MCP servers via its dedicated configuration file. Two levels are available:\n- **Global** (all projects): `~/.kiro/settings/mcp.json`\n- **Workspace** (this repository only): `.kiro/settings/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"einvoicing-de\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-einvoicing-de\"],\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\nThe file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.\n\n## Available tools\n\n| Tool | Description |\n|------|-------------|\n| `invoice_create` | Generate ZUGFeRD or XRechnung XML (CII or UBL). Enforces the §14 Abs. 2 UStG B2B mandate: non-XML output is rejected for DE-prefixed VAT buyers unless `transitional_period_opt_in=True` is set. `output_format='pdf'` produces a PDF/A-3 level B hybrid invoice with sRGB ICC profile, OutputIntent, embedded fonts, and deterministic /ID. |\n| `invoice_validate` | Validate an invoice against EN 16931 and KoSIT rules (BR-DE-\\*). Local Schematron validation runs by default (no data leaves your machine); set `cloud_validate=True` or `EINVOICING_DE_KOSIT_ENABLE=1` to opt into KoSIT cloud validation (`validator.kosit.de` or a self-hosted endpoint) with exponential backoff retry (1s/2s/4s). XSLT 2.0 local validation requires the `[xslt2]` extra. |\n| `invoice_parse` | Extract structured data from ZUGFeRD or XRechnung XML, or from a PDF/A-3 hybrid invoice with embedded `factur-x.xml` / `zugferd-invoice.xml`. |\n| `invoice_convert` | Convert between ZUGFeRD profiles, swap ZUGFeRD/XRechnung CII headers, or perform cross-syntax CII/UBL conversion via core `convert_wire_format`. |\n| `datev_export` | Export a ZUGFeRD invoice as a DATEV EXTF 700 Buchungsstapel CSV file for import into DATEV accounting software. Defaults to SKR 03 accounts (8400 revenue / 10000 receivable). |\n| `tax_rules` | Query German VAT rules (rates, §13b UStG reverse charge codes, §19 UStG Kleinunternehmer thresholds at JStG 2024 values of €25,000 preceding year / €100,000 current year, exemptions). |\n\n### Peppol network tools\n\nPeppol participant lookup, service-endpoint lookup, a DNS-only diagnostic, AS4 send, Peppol Directory search, 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`.\n\n`peppol_send` signs outbound messages with a real `wsse:Security` signature as of `mcp-einvoicing-core` v1.20.0 (previously computed and discarded — see CHANGELOG.md v0.10.0).\n\n| Tool | Description |\n|---|---|\n| `peppol_lookup_participant` | Check whether a business is registered on the Peppol network; returns registration status and supported document types |\n| `peppol_get_service_endpoint` | Fetch the AS4 endpoint for a participant's document type |\n| `resolve_peppol_dns` | DNS-only (SML) diagnostic, independent of SMP reachability |\n| `peppol_send` | Transmit a UBL/CII invoice via AS4 |\n| `peppol_directory_search` | Search the public Peppol Directory by participant, name, country, or document type |\n| `list_participant_id_schemes`, `list_document_type_ids`, `list_process_ids`, `list_spis_use_case_ids` | OpenPeppol eDEC codelist lookups (require `EINVOICING_PEPPOL_CODELIST_DIR`) |\n| `check_document_type_id_in_codelist`, `check_process_id_in_codelist`, `check_participant_id_scheme_in_codelist`, `get_peppol_codelist_version` | OpenPeppol eDEC codelist checks and version reporting |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n### Peppol reporting and status tools\n\nAdded in v0.10.0 via three opt-in core plugins, mounted unconditionally in `server.py`. Each raises a clear error at call time (not at registration) if its extra or data directory is missing.\n\n| Tool | Plugin | Description |\n|---|---|---|\n| `validate_eusr_report` | `register_peppol_reporting_tools` | Validate an End User Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_tsr_report` | `register_peppol_reporting_tools` | Validate a Transaction Statistics Report (XSD, then Schematron). Requires the `[xslt2]` extra. |\n| `validate_mls_message` | `register_peppol_mls_tools` | Validate a Message Level Status document (UBL `ApplicationResponse-2` subset). Requires the `[xslt2]` extra. |\n| `build_mls_message` | `register_peppol_mls_tools` | Build a document-level MLS response. Requires the `[xslt2]` extra. |\n| 13 `list_*`/`check_*` pairs, `get_en16931_codelist_version` | `register_en16931_codelist_tools` | EN 16931 semantic code list lookups/checks (units, VAT categories, etc.). Require `EINVOICING_EN16931_CODELIST_DIR`. |\n\nSee the [`mcp-einvoicing-core` README](https://github.com/cmendezs/mcp-einvoicing-core#readme) for full parameter documentation on these tools.\n\n### Usage examples\n\n**Example 1: Validate an invoice**\n\n```\n1. invoice_validate(\n     xml_base64=\"...\",   # Base64-encoded ZUGFeRD XML\n     strict=True\n   )\n   → {\n       \"is_valid\": true,\n       \"profile\": \"EN_16931\",\n       \"syntax\": \"CII\",\n       \"error_count\": 0,\n       \"warning_count\": 2,\n       \"errors\": [],\n       \"warnings\": [...],\n       \"validator_used\": \"local_schematron\"\n     }\n```\n\n**Example 2: Query German tax rules**\n\n```\n2. tax_rules(query=\"reverse_charge\", context=\"Bauleistungen\")\n   → {\n       \"results\": [\n         {\n           \"paragraph\": \"§13b Abs. 2 Nr. 5 UStG\",\n           \"description_en\": \"Construction services (building contractor rule)\",\n           \"vatex_code\": \"VATEX-EU-AE\",\n           \"invoice_note\": \"Steuerschuldnerschaft des Leistungsempfängers (§13b UStG)\"\n         }\n       ],\n       \"legal_disclaimer\": \"...\"\n     }\n```\n\n**Example 3: Check Peppol registration**\n\n```\n3. peppol_lookup_participant(\n     identifier=\"123456789\",   # bare USt-IdNr, normalized to 9930:DE123456789\n     environment=\"production\"\n   )\n   → {\n       \"is_registered\": true,\n       \"participant_id\": \"9930:DE123456789\",\n       \"supported_document_types\": [\"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0\"],\n       \"smp_hostname\": \"b-...iso6523-actorid-upis.edelivery.tech.ec.europa.eu\"\n     }\n```\n\n**Example 4: Parse invoice data**\n\n```\n4. invoice_parse(xml_base64=\"...\", include_raw_xml=False)\n   → {\n       \"profile\": \"XRECHNUNG\",\n       \"syntax\": \"CII\",\n       \"invoice_number\": \"RE-2025-001\",\n       \"invoice_date\": \"2025-01-15\",\n       \"seller_name\": \"Muster GmbH\",\n       \"buyer_name\": \"Käufer AG\",\n       \"tax_inclusive_amount\": \"119.00\",\n       \"currency_code\": \"EUR\"\n     }\n```\n\n## Architecture\n\n```\nmcp-einvoicing-de (this package, standalone MCP server)\n├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic models (all profiles)\n├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* rules\n├── KoSITValidator                     ← Remote validation tool (optional)\n└── Tools: create / validate / parse / convert / datev_export / tax_rules\n    (+ core Peppol tool plugin, mounted separately: lookup / send / DNS / codelists)\n\n        ↑ extends\nmcp-einvoicing-core (shared base, installed as dependency)\n├── BaseDocumentGenerator / Validator / Parser\n├── BaseInvoice, BaseParty … (Pydantic)\n├── xml_utils, exceptions\n└── EInvoicingMCPServer\n```\n\n## Supported standards\n\n| Standard | Version | Profiles / Syntax |\n|----------|---------|-------------------|\n| ZUGFeRD | 2.5.2 | MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED |\n| XRechnung | 3.0.2 | CII (Cross Industry Invoice), UBL (Universal Business Language) |\n| KoSIT `xrechnung-schematron` ruleset | 2.6.0 | Validation rules for XRechnung 3.0.2 (separate version axis from the spec itself) |\n| EN 16931 | 2017 | European core data model for electronic invoicing |\n| Peppol BIS | 3.0 | Billing 3.0 (EN 16931-compliant) |\n\n> **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.\n\n| Resource | Link |\n|----------|------|\n| FeRD ZUGFeRD specification | [ferd-net.de](https://www.ferd-net.de) |\n| KoSIT XRechnung | [xeinkauf.de](https://xeinkauf.de/xrechnung/) |\n| KoSIT validation tool | [github.com/itplr-kosit/validationtool](https://github.com/itplr-kosit/validationtool) |\n| EN 16931-1:2017 | [CEN](https://www.cen.eu/) |\n| Peppol BIS Billing 3.0 | [docs.peppol.eu](https://docs.peppol.eu/poacc/billing/3.0/) |\n\n## Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run the full test suite\npytest tests/ -v\n\n# With coverage report\npytest --cov=mcp_einvoicing_de --cov-report=term-missing\n\n# Model tests only\npytest tests/test_models.py -v\n```\n\n## Contributing\n\nContributions are welcome. Please open an issue before submitting a pull request for significant changes.\n\n```bash\ngit clone https://github.com/cmendezs/mcp-einvoicing-de.git\ncd mcp-einvoicing-de\npip install -e \".[dev]\"\npytest\nmake audit\n```\n\n## Other e-invoicing MCP servers\n\n| Country | Server |\n|---------|--------|\n| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |\n| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |\n| 🇧🇷 Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |\n| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |\n| 🇩🇪 Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |\n| 🇮🇳 India | [mcp-einvoicing-in](https://github.com/cmendezs/mcp-einvoicing-in) |\n| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| 🇲🇽 Mexico | [mcp-cfdi-mx](https://github.com/cmendezs/mcp-cfdi-mx) |\n| 🇵🇱 Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| 🇸🇬 Singapore | [mcp-invoicenow-sg](https://github.com/cmendezs/mcp-invoicenow-sg) |\n| 🇪🇸 Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n| 🇦🇪 United Arab Emirates | [mcp-einvoicing-ae](https://github.com/cmendezs/mcp-einvoicing-ae) |\n\n## License\n\nThis project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details. For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 15264,
  "sha": "63f18b9c469d8f0225ef50c63af5c11bddf815135348c514f20ecb439d2ee9ab",
  "repo_slug": "cmendezs/mcp-einvoicing-de",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_einvoicing_de_9299def4/readme"
}