mcp-einvoicing-de 🇩🇪

Name: mcp-einvoicing-de
Author: cmendezs

License PyPI version Python mcp-einvoicing-de MCP server

Servidor MCP (Model Context Protocol) en Python para la factura electrónica alemana en los formatos ZUGFeRD 2.x y XRechnung 3.x (EN 16931, FeRD, KoSIT). Permite a los agentes de IA (Claude, IDEs) crear, validar, analizar y convertir facturas electrónicas que cumplen totalmente con el mandato alemán de facturación electrónica B2B (válido a partir de 2025, con implementación gradual hasta 2027–2028) y la norma europea EN 16931.

Resumen en inglés

Este es un servidor de Protocolo de Contexto de Modelo (MCP) para la facturación electrónica alemana. Expone 6 herramientas que cubren el ciclo de vida completo de una factura ZUGFeRD o XRechnung: creación (CII/UBL XML), validación según las reglas Schematron de EN 16931 y KoSIT (BR-DE-*), análisis de archivos de factura existentes, conversión de perfiles y sintaxis, búsqueda de registro de participantes Peppol (AS4) y reglas de IVA alemanas (clases impositivas, inversión del sujeto pasivo según §13b UStG, exenciones). Admite todos los perfiles de ZUGFeRD 2.x (desde MINIMUM hasta EXTENDED) y XRechnung 3.x (sintaxis CII y UBL). Licenciado bajo Apache 2.0.

Construido sobre

Este paquete se basa en mcp-einvoicing-core, una biblioteca base común para servidores MCP de facturación electrónica europea. Proporciona modelos comunes, abstracciones de validación, funciones auxiliares XML y la jerarquía de excepciones.

mcp-einvoicing-core se instala automáticamente como una dependencia transitiva; no se requiere ningún paso adicional.

Para desarrolladores: pip install -e ".[dev]" instala el paquete base automáticamente desde PyPI.

🏗️ Arquitectura

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

🚀 Instalación

A través de PyPI (recomendado)

pip install mcp-einvoicing-de

Sin instalación previa con uvx:

uvx mcp-einvoicing-de

Desde las fuentes

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

⚙️ Configuración

El servidor no requiere credenciales externas en la versión v0.1.0. Variables de entorno disponibles:

Variable	Descripción	Estándar
`EINVOICING_DE_LOG_LEVEL`	Nivel de registro (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`EINVOICING_DE_KOSIT_VALIDATOR_URL`	URL de la herramienta de validación KoSIT (opcional, para validación remota)	—
`EINVOICING_DE_PEPPOL_SMP_URL`	URL de búsqueda Peppol-SMP (opcional)	—
`EINVOICING_DE_PDF_ENGINE`	Motor de generación de PDF (`reportlab` o `pymupdf`)	`reportlab`

🤖 Integración con Claude Desktop

Entrada en el archivo claude_desktop_config.json:

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

⌨️ Integración con Cursor

Archivo de configuración (~/.cursor/mcp.json o .cursor/mcp.json en el directorio del proyecto):

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

🪐 Integración con Kiro

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

🧰 Herramientas MCP disponibles

Herramienta	Descripción
`invoice_create`	Generar XML de ZUGFeRD o XRechnung (CII o UBL); PDF/A-3 híbrido planificado (v0.2.0)
`invoice_validate`	Comprobar factura contra EN 16931 y reglas Schematron de KoSIT (BR-DE-*)
`invoice_parse`	Extraer datos estructurados de un archivo ZUGFeRD o XRechnung existente
`invoice_convert`	Convertir entre perfiles ZUGFeRD o ZUGFeRD ↔ XRechnung
`peppol_check`	Comprobar el registro de participante Peppol de una empresa alemana (AS4)
`tax_rules`	Consultar reglas de IVA alemanas (clases impositivas, §13b UStG, exenciones)

Ejemplos de uso

Ejemplo 1 — Validar factura

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

Ejemplo 2 — Consultar reglas fiscales alemanas

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

Ejemplo 3 — Comprobar registro 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"
     }

Ejemplo 4 — Analizar datos de factura

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

📚 Estándares soportados

Estándar	Versión	Perfiles / Sintaxis
ZUGFeRD	2.3	MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
XRechnung	3.x	CII (Cross Industry Invoice), UBL (Universal Business Language)
EN 16931	—	Modelo de datos central europeo para la factura electrónica
Peppol BIS	3.0	Billing 3.0 (DE PINT)

Nota: ZUGFeRD 2.x y XRechnung 3.x comparten la misma sintaxis CII-XML a nivel de perfil EN 16931. Por lo tanto, es posible convertir entre ambos formatos sin pérdida de datos. El perfil EXTENDED es específico de ZUGFeRD y no tiene equivalente en XRechnung.

Recurso	Enlace
Especificación FeRD ZUGFeRD	ferd-net.de
KoSIT XRechnung	xeinkauf.de
Herramienta de validación KoSIT	github.com/itplr-kosit/validationtool
EN 16931-1:2017	CEN
Peppol BIS Billing 3.0	docs.peppol.eu

🧪 Pruebas

# 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

Hoja de ruta

Versión	Funciones
v0.1.0 (actual)	Herramientas: create, validate, parse, convert, peppol_check, tax_rules
v0.2.0	Incrustación de PDF/A-3 (ZUGFeRD-Hybrid) vía `reportlab` / `PyMuPDF`
v0.3.0	Validador en línea KoSIT totalmente integrado
v0.4.0	Transmisión directa Peppol AS4
v0.5.0	Formato de exportación DATEV
v1.0.0	Listo para producción, cobertura completa de EN 16931

Contribuir

Las contribuciones son bienvenidas. Por favor, abra un issue antes de enviar un Pull Request para cambios significativos.

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make audit

Otros servidores MCP de facturación electrónica

País	Servidor
🌍 Global	mcp-einvoicing-core
🇧🇪 Bélgica	mcp-einvoicing-be
🇫🇷 Francia	mcp-facture-electronique-fr
🇮🇹 Italia	mcp-fattura-elettronica-it
🇩🇪 Alemania	mcp-einvoicing-de

📄 Licencia

Este proyecto está bajo la licencia Apache-2.0. Consulte el archivo LICENSE para obtener más detalles.

Proyecto mantenido por cmendezs. Para preguntas sobre la implementación de la especificación ZUGFeRD o XRechnung, por favor abra un issue.

mcp-einvoicing-de