mcp-facturacion-electronica-es 🇪🇸

Introducción

mcp-facturacion-electronica-es es un servidor MCP (Model Context Protocol) especializado en facturación electrónica española. Proporciona herramientas para generar, validar y enviar facturas electrónicas bajo los seis sistemas coexistentes en España: VERI*FACTU, Facturae/FACe, SII, TicketBAI (País Vasco), NaTicket (Navarra) y las obligaciones B2B de la Ley 18/2022 "Crea y Crece". El servidor está construido sobre mcp-einvoicing-core, la librería base compartida con mcp-facture-electronique-fr (Francia, XP Z12-013) y mcp-einvoicing-be (Bélgica, Peppol BIS 3.0).

For non-Spanish developers: Spain operates one of the most complex e-invoicing landscapes in Europe — six overlapping systems apply depending on taxpayer size, sector, and region. VERI*FACTU (Royal Decree 1007/2023, Order HAC/1177/2024) is the forthcoming mandatory real-time invoice registry for non-SII taxpayers, with hard deadlines in January and July 2027 (RD-ley 15/2025). SII (Suministro Inmediato de Información — Immediate Information Supply) already applies to large taxpayers (>€6M turnover). The Basque Country runs TicketBAI and Navarre runs NaTicket, both independent of the national AEAT framework. B2G invoicing via Facturae XML on the FACe portal has been mandatory since 2015 (Ley 25/2013).

Construido sobre

Este paquete se basa en mcp-einvoicing-core, la librería base compartida por todos los servidores MCP del ecosistema mcp-einvoicing. Proporciona modelos comunes, abstracciones de validación, utilidades XML y la jerarquía de excepciones.

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

Descripción general

El ecosistema español de facturación electrónica cuenta con seis sistemas coexistentes con ámbitos, formatos y calendarios distintos. VERI*FACTU introduce registros de factura inviolables encadenados que se envían en tiempo real a la AEAT (Agencia Estatal de Administración Tributaria), aplicable a la mayoría de empresas a partir de 2027 (RD-ley 15/2025). El SII ya es obligatorio para grandes contribuyentes bajo una ventana de comunicación de 4 días. Facturae XML con firma XAdES-EPES cubre toda la facturación B2G a través del portal FACe. El País Vasco aplica TicketBAI de forma independiente, con tres autoridades provinciales que mantienen cada una sus propios esquemas XSD y endpoints. Navarra opera NaTicket. La Ley Crea y Crece exige la facturación electrónica B2B para todas las empresas, con formato pendiente del reglamento de desarrollo. La detección del régimen a partir del domicilio fiscal y el volumen de operaciones es un requisito previo a todas las demás operaciones — utilice es__detect_regional_regime en primer lugar.

Cobertura regulatoria

Exclusión mutua SII / VERI*FACTU (Real Decreto 254/2025): Los contribuyentes inscritos en el SII quedan exentos de VERI*FACTU. Utilice es__check_b2b_mandate_applicability antes de generar cualquier registro.

Herramientas

VERI*FACTU

es__generate_verifactu_record

Genera un registro de factura inviolable (Orden HAC/1177/2024) con encadenamiento SHA-256 Huella que lo vincula al registro anterior.

{
  "tool": "es__generate_verifactu_record",
  "arguments": {
    "invoice": { "date": "2025-03-15", "number": "2025-0042", "currency": "EUR",
      "seller": { "tax_id": { "country_code": "ES", "identifier": "B12345678" }, "name": "Empresa SL" },
      "buyer":  { "tax_id": { "country_code": "ES", "identifier": "A98765432" }, "name": "Cliente SA" },
      "lines": [{ "line_number": 1, "description": "Servicios", "quantity": 10, "unit_price": 100.00, "vat_rate": 21.0 }]
    },
    "previous_hash": "3C4A9B...", "software_id": "SW-001", "software_nif": "B87654321", "invoice_type": "F1"
  }
}

⚠️ Pendiente de confirmación regulatoria — XSD v1.0 (HAC/1177/2024) no validado aún contra el entorno de pruebas de la AEAT.

es__validate_verifactu_record

Valida un registro VERI*FACTU XML contra el XSD oficial publicado con la Orden HAC/1177/2024 (BOE-A-2024-22138).

{ "tool": "es__validate_verifactu_record", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>" } }

⚠️ Pendiente de confirmación regulatoria

es__submit_verifactu_to_aeat

Envía un registro VERI*FACTU firmado al endpoint en tiempo real de la AEAT mediante MTLS (certificado FNMT-RCM Clase 1). Respeta AEAT_ENV=sandbox|production.

{ "tool": "es__submit_verifactu_to_aeat", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>", "nif": "B12345678" } }

⚠️ Pendiente de confirmación regulatoria — AuthMode.MTLS no está implementado aún en mcp-einvoicing-core; registrado en el backlog de gaps del core.

es__generate_qr_verifactu

Genera el código QR obligatorio de VERI*FACTU (HAC/1177/2024 Art. 10) como PNG en base64. Codifica la URL de verificación de la AEAT con el texto "Factura verificable en la sede electrónica de la AEAT". Candidato a promoción a mcp-einvoicing-core (generación de QR).

{ "tool": "es__generate_qr_verifactu", "arguments": { "nif": "B12345678", "invoice_number": "2025-0042", "invoice_date": "2025-03-15", "total_amount": 1210.00 } }

⚠️ Pendiente de confirmación regulatoria

es__cancel_verifactu_record

Genera un registro de anulación VERI*FACTU (IndicadorAnulacion=S, TipoHuella=01) encadenado a la secuencia de huellas actual.

{ "tool": "es__cancel_verifactu_record", "arguments": { "original_invoice_number": "2025-0042", "original_invoice_date": "2025-03-15", "issuer_nif": "B12345678", "previous_hash": "3C4A9B..." } }

⚠️ Pendiente de confirmación regulatoria

Facturae / FACe

es__generate_facturae_xml

Genera una factura XML conforme a Facturae 3.2.2 para su envío B2G. Utiliza InvoiceDocument de mcp-einvoicing-core.

{ "tool": "es__generate_facturae_xml", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042", "seller": { "tax_id": { "country_code": "ES", "identifier": "B12345678" }, "name": "Proveedor SL" }, "buyer": { "tax_id": { "country_code": "ES", "identifier": "S2800000D" }, "name": "Ayuntamiento de Madrid" }, "lines": [{ "line_number": 1, "description": "Suministro", "quantity": 5, "unit_price": 200.00, "vat_rate": 21.0 }] } } }

⚠️ Pendiente de confirmación regulatoria

es__sign_facturae_xades

Aplica una firma digital XAdES-EPES (ETSI EN 319 132-1) a un documento Facturae XML. Candidato a promoción a mcp-einvoicing-core (firma XAdES — puntuación 3/3).

{ "tool": "es__sign_facturae_xades", "arguments": { "xml": "<Facturae>...</Facturae>", "cert_path": "/certs/empresa.p12", "cert_password": "s3cr3t" } }

⚠️ Pendiente de confirmación regulatoria

es__submit_to_face

Envía un XML Facturae firmado a FACe (Punto General de Entrada de Facturas Electrónicas) a través de la API REST B2B de FACe v2. Requiere OAuth2 (FACE_CLIENT_ID / FACE_CLIENT_SECRET).

{ "tool": "es__submit_to_face", "arguments": { "xml": "<Facturae>...</Facturae>", "administrative_unit": "U00000038", "accounting_office": "U00000038", "management_body": "U00000038" } }

⚠️ Pendiente de confirmación regulatoria

es__get_face_invoice_status

Consulta el estado de tramitación de una factura en FACe. Devuelve los códigos estándar: 1200 (Registrada), 2400 (Reconocida), 3100 (Rechazada), 4100 (Pagada).

{ "tool": "es__get_face_invoice_status", "arguments": { "invoice_id": "FAC-2025-00012345" } }

⚠️ Pendiente de confirmación regulatoria

es__validate_facturae_schema

Valida un XML Facturae contra el XSD oficial de Facturae 3.2.2 mediante lxml. Devuelve errores estructurados con ubicaciones XPath.

{ "tool": "es__validate_facturae_schema", "arguments": { "xml": "<Facturae>...</Facturae>" } }

⚠️ Pendiente de confirmación regulatoria

SII (Suministro Inmediato de Información)

es__build_sii_invoice_record

Construye un registro XML AEAT SII (emisión FacturaExpedida o recepción FacturaRecibida) conforme a la guía técnica SII de la AEAT v3.0 (abril 2024). Soporta TipoComunicacion A0/A1/A4.

{ "tool": "es__build_sii_invoice_record", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "record_type": "issued", "communication_type": "A0" } }

⚠️ Pendiente de confirmación regulatoria

es__submit_sii_batch

Envía un lote de facturas (máximo 10.000 registros) al endpoint SOAP SII de la AEAT. Requiere MTLS.

{ "tool": "es__submit_sii_batch", "arguments": { "records": ["<RegistroLRFacturasEmitidas>...</RegistroLRFacturasEmitidas>"], "record_type": "issued", "fiscal_year": 2025 } }

⚠️ Pendiente de confirmación regulatoria — AuthMode.MTLS no está implementado aún en mcp-einvoicing-core.

es__query_sii_status

Consulta el estado de un lote SII enviado mediante ConsultaFactInformadasEmitidas o ConsultaFactInformadasRecibidas.

{ "tool": "es__query_sii_status", "arguments": { "batch_id": "SII-BATCH-20250315-001", "record_type": "issued" } }

⚠️ Pendiente de confirmación regulatoria

es__generate_sii_correction

Genera un registro de modificación SII (A1) o baja (A4) que referencia la factura original mediante IDFactura. El constructor de facturas rectificativas es candidato a mcp-einvoicing-core (puntuación 3/3).

{ "tool": "es__generate_sii_correction", "arguments": { "original_invoice": { "number": "2025-0042" }, "correction_type": "A1", "record_type": "issued" } }

⚠️ Pendiente de confirmación regulatoria

TicketBAI

es__generate_ticketbai_xml

Genera una factura XML TicketBAI con firma XAdES y cadena HuellaTBAI. Selecciona automáticamente el XSD provincial correcto: Álava v1.2, Gipuzkoa v1.2, Bizkaia v2.1.

{ "tool": "es__generate_ticketbai_xml", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "province": "gipuzkoa", "software_license": "TBAI-GI-12345", "cert_path": "/certs/empresa.p12", "cert_password": "s3cr3t" } }

⚠️ Pendiente de confirmación regulatoria — los tres XSD provinciales deben empaquetarse por separado; no se deben validar cruzadamente entre provincias.

es__submit_ticketbai

Envía un registro TicketBAI XML a la autoridad provincial vasca correspondiente. El endpoint se enruta automáticamente: Álava (batuz.eus), Gipuzkoa (tbai.egoitza.gipuzkoa.eus), Bizkaia (www.bizkaia.eus/ogasun).

{ "tool": "es__submit_ticketbai", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "bizkaia", "nif": "B12345678" } }

⚠️ Pendiente de confirmación regulatoria

es__validate_ticketbai_schema

Valida un documento XML TicketBAI contra el XSD provincial correcto. Los esquemas no son intercambiables entre provincias.

{ "tool": "es__validate_ticketbai_schema", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "gipuzkoa" } }

⚠️ Pendiente de confirmación regulatoria

Crea y Crece / B2B

es__generate_b2b_einvoice_es

Genera una factura B2B conforme a EN 16931 en formato UBL 2.1 o Facturae 3.2.2 según la Ley 18/2022.

{ "tool": "es__generate_b2b_einvoice_es", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "format": "ubl" } }

⚠️ Pendiente de confirmación regulatoria — el reglamento de desarrollo del mandato B2B no está publicado aún.

es__check_b2b_mandate_applicability

Determina el régimen aplicable (VERI*FACTU, SII, TicketBAI, NaTicket) a partir del volumen de operaciones, el código de provincia y la inscripción en el SII. Aplica la lógica de exclusión mutua del Real Decreto 254/2025.

{ "tool": "es__check_b2b_mandate_applicability", "arguments": { "annual_turnover_eur": 2500000, "tax_address_province_code": "28", "enrolled_in_sii": false, "entity_type": "IS" } }

⚠️ Pendiente de confirmación regulatoria

Herramientas de utilidad

es__detect_regional_regime

Detecta el régimen de facturación electrónica aplicable a partir del código de provincia INE. Devuelve VERIFACTU, TICKETBAI, NATICKET o VERIFACTU+SII.

Provincias vascas: 01 Álava, 20 Gipuzkoa, 48 Bizkaia. Navarra: 31. El resto devuelve VERIFACTU. Candidato a promoción a mcp-einvoicing-core.

{ "tool": "es__detect_regional_regime", "arguments": { "province_code": "20", "enrolled_in_sii": false } }

⚠️ Pendiente de confirmación regulatoria

es__get_compliance_status

Devuelve los plazos de mandato vigentes y el sistema operativo para un perfil de empresa. Refleja el RD-ley 15/2025 — sujeto a cambios por legislación posterior. Candidato a promoción a mcp-einvoicing-core (registro genérico de plazos).

{ "tool": "es__get_compliance_status", "arguments": { "entity_type": "IS", "province_code": "28", "annual_turnover_eur": 1000000, "enrolled_in_sii": false } }

⚠️ Pendiente de confirmación regulatoria

es__parse_aeat_response

Analiza y normaliza una respuesta XML de la AEAT (VERI*FACTU o SII) en JSON estructurado. Extrae EstadoEnvio (Correcto/AceptadoConErrores/Incorrecto), CSV (código seguro de verificación) y detalle de errores. Candidato a promoción a mcp-einvoicing-core (analizador genérico de respuestas XML de proveedores — puntuación 2/3).

{ "tool": "es__parse_aeat_response", "arguments": { "xml": "<RespuestaRegFactuSistemaFacturacion>...</RespuestaRegFactuSistemaFacturacion>", "response_type": "verifactu" } }

⚠️ Pendiente de confirmación regulatoria

Instalación

Desde PyPI (recomendado)

pip install mcp-facturacion-electronica-es

Sin instalación previa, con uvx:

uvx mcp-facturacion-electronica-es

Desde las fuentes

git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git
cd mcp-facturacion-electronica-es
uv sync --all-extras

Configuración

Claude Desktop

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/ruta/al/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "contraseña-del-certificado"
      }
    }
  }
}

Toda la configuración se realiza mediante variables de entorno o un archivo .env.

AEAT / VERI*FACTU / SII

FACe

TicketBAI

Comunes (heredadas de mcp-einvoicing-core)

Arquitectura

mcp-facturacion-electronica-es es un adaptador de país dentro de la familia mcp-einvoicing, construido sobre mcp-einvoicing-core.

mcp-einvoicing-core (v0.1.0+)
│   BaseDocumentGenerator, BaseDocumentValidator, BaseLifecycleManager
│   InvoiceDocument, InvoiceParty, InvoiceLineItem, VATSummary, PaymentTerms
│   EInvoicingError, ValidationError, XSDValidationError, PlatformError
│   BaseEInvoicingClient, OAuthConfig, AuthMode (OAUTH2 / BEARER / MTLS)
│   get_logger, format_amount, xml_element, format_error
│
├── mcp-facture-electronique-fr    (Francia — XP Z12-013, Chorus Pro)
├── mcp-einvoicing-be              (Bélgica — Peppol BIS 3.0, PINT-BE, Mercurius)
├── mcp-facturacion-electronica-es (España — este paquete)
│   ├── verifactu/   generación de registros, cadena hash, QR, anulación
│   ├── facturae/    XML Facturae 3.2.2, XAdES-EPES, envío FACe
│   ├── sii/         construcción de lotes, SOAP AEAT, rectificaciones
│   ├── ticketbai/   generación XML, enrutamiento provincial, validación
│   ├── b2b/         UBL/Facturae Crea y Crece, detector de mandato
│   └── utils/       detección de régimen, analizador respuestas AEAT, registro de plazos
├── mcp-fattura-elettronica-it     (Italia — FatturaPA / SDI)
└── mcp-ksef-pl                    (Polonia — KSeF / FA(2))

Funciones candidatas a mcp-einvoicing-core

Notas de cumplimiento normativo

Aviso: Las fechas de mandato reflejan el RD-ley 15/2025 (diciembre 2025) y están sujetas a cambios por legislación posterior o instrucciones administrativas de la AEAT. Este software no constituye asesoramiento jurídico ni fiscal.

Calendario de mandatos

Excepciones regionales

• País Vasco: TicketBAI aplica en lugar de VERI*FACTU. Cada una de las tres provincias (Álava, Gipuzkoa, Bizkaia) tiene un XSD, endpoint y proceso de certificación de software distintos. Los endpoints nacionales de la AEAT no aplican.

• Navarra: Aplica NaTicket (Hacienda Foral de Navarra). VERI*FACTU no aplica.

• Ceuta / Melilla: IPSI (no IVA); la aplicabilidad del SII/VERI*FACTU difiere — verificar con la AEAT.

• Exclusión mutua SII / VERI*FACTU: El Real Decreto 254/2025 hace estos sistemas mutuamente excluyentes. Los contribuyentes inscritos en el SII no envían registros VERI*FACTU.

Todos los endpoints de envío de la AEAT requieren un certificado FNMT-RCM o de CA acreditada. La AEAT dispone de un entorno de pruebas gratuito en prewww2.aeat.es.

Tests

# Instalar dependencias de desarrollo
uv sync --all-extras

# Ejecutar la suite de tests completa
uv run pytest tests/ -v

# Con informe de cobertura
uv run pytest --cov=mcp_facturacion_electronica_es --cov-report=term-missing

Hoja de ruta

Los elementos pendientes se han extraído directamente de los marcadores [NEED] presentes en el código fuente. Cada versión es un prerequisito de la siguiente y debe pasar el audit gate (make audit) antes de publicarse.

v0.1.0 (actual) — Scaffold y generación local

Herramientas implementadas con XML válido generado localmente, validación estructural, lógica de régimen y firma XAdES. Sin envíos a plataformas externas confirmados contra entornos reales.

v0.2.0 — Bundle de esquemas XSD y correcciones de protocolo

Validación XSD completa (ahora solo estructural):

Políticas de firma XAdES:

Correcciones de protocolo:

v0.3.0 — Verificación de endpoints y sandbox

AEAT — VERI*FACTU:

AEAT — SII:

FACe:

TicketBAI:

v0.4.0 — Cadena completa y lotes SII correctos

v0.5.0 — Crea y Crece B2B + endurecimiento del audit

v1.0.0 — Preparado para producción

• Todas las verificaciones de sandbox completadas

• Todas las validaciones XSD habilitadas (specs/ poblado)

• Cobertura completa del mandato VERI*FACTU (enero y julio 2027)

• Software TicketBAI certificado por las tres provincias vascas

• Reglamento Crea y Crece B2B publicado e implementado

• Audit gate sin ningún aviso (exit code 0)

Contribuir

Abra un issue antes de iniciar trabajo significativo. Para lógica de utilidad reutilizable entre adaptadores de país, abra un issue de core-promotion en mcp-einvoicing-core antes de implementarla — utilice la rúbrica de puntuación (3 = DEBE promoverse, 2 = DEBERÍA, 1 = mantener aquí).

git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git
cd mcp-facturacion-electronica-es
uv sync --all-extras
uv run pytest
make audit

Todas las afirmaciones regulatorias deben referenciar una publicación específica del BOE, una versión oficial del XSD o una versión de la guía técnica de la AEAT. No elimine ⚠️ Pendiente de confirmación regulatoria sin enlazar la fuente verificada en la descripción del PR.

Resumen del Audit — Fase 1

Este README es el documento de especificación para la fase de implementación. Los badges de las herramientas se actualizarán a ✅ a medida que cada herramienta supere la verificación regulatoria.

Other e-invoicing MCP servers

Licencia

Publicado bajo la licencia Apache 2.0. Copyright 2025–2026 Christophe Méndez y colaboradores.