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), que 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.
España opera uno de los ecosistemas de facturación electrónica más complejos de Europa, con seis sistemas superpuestos que se aplican en función del tamaño del contribuyente, el sector y la región. VERI*FACTU (Real Decreto 1007/2023, Orden HAC/1177/2024) es el próximo registro obligatorio de facturas en tiempo real para contribuyentes no inscritos en el SII, con plazos firmes en enero y julio de 2027 (RD-ley 15/2025). El SII (Suministro Inmediato de Información) ya se aplica a grandes contribuyentes (facturación >6M EUR). El País Vasco opera TicketBAI y Navarra opera NaTicket, ambos independientes del marco nacional de la AEAT. La facturación B2G mediante Facturae XML en el portal FACe es obligatoria desde 2015 (Ley 25/2013).
Instalación
Desde PyPI (recomendado)
pip install mcp-facturacion-electronica-esSin instalación previa, con uvx:
uvx mcp-facturacion-electronica-esDesde las fuentes
git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.gitcd mcp-facturacion-electronica-esuv sync --all-extrasConfiguración
Toda la configuracion se realiza mediante variables de entorno o un archivo .env.
AEAT / VERI*FACTU / SII
| Variable | Descripcion | Obligatorio |
|---|---|---|
AEAT_ENV |
sandbox o production |
Si |
AEAT_CERTIFICATE_PATH |
Ruta al certificado PKCS#12 FNMT-RCM | Para el envio |
AEAT_CERTIFICATE_PASSWORD |
Contrasena del certificado | Para el envio |
AEAT_NIF |
NIF del contribuyente | Para el envio |
FACe
| Variable | Descripcion | Obligatorio |
|---|---|---|
FACE_ENV |
sandbox o production |
Si |
FACe se autentica mediante JWS usando el mismo certificado AEAT_CERTIFICATE_PATH /
AEAT_CERTIFICATE_PASSWORD que VERI*FACTU/SII (ver la seccion AEAT anterior); no se
requieren credenciales FACe independientes.
TicketBAI
| Variable | Descripcion | Obligatorio |
|---|---|---|
TICKETBAI_ENV |
sandbox o production |
Si |
TICKETBAI_CERTIFICATE_PATH |
Ruta del certificado de firma provincial | Si |
TICKETBAI_CERTIFICATE_PASSWORD |
Contrasena del certificado | Si |
Comunes (heredadas de mcp-einvoicing-core)
| Variable | Descripcion | Por defecto |
|---|---|---|
LOG_LEVEL |
DEBUG, INFO, WARNING, ERROR |
INFO |
Integración con Claude Desktop
Para usar este servidor con Claude, añada esta configuración a su archivo claude_desktop_config.json:
{ "mcpServers": { "facturacion-es": { "command": "uvx", "args": ["mcp-facturacion-electronica-es"], "env": { "AEAT_ENV": "sandbox", "AEAT_CERTIFICATE_PATH": "/ruta/al/cert.p12", "AEAT_CERTIFICATE_PASSWORD": "contrasena-del-certificado" } } }}Integración con Cursor
Cursor admite servidores MCP via stdio. Añada la configuración en:
- Global (todos los proyectos):
~/.cursor/mcp.json - Proyecto (solo este repositorio):
.cursor/mcp.json
{ "mcpServers": { "facturacion-es": { "command": "uvx", "args": ["mcp-facturacion-electronica-es"], "env": { "AEAT_ENV": "sandbox", "AEAT_CERTIFICATE_PATH": "/ruta/al/cert.p12", "AEAT_CERTIFICATE_PASSWORD": "contrasena-del-certificado" } } }}Recargue la ventana de Cursor (Ctrl+Shift+P y luego Reload Window) para aplicar los cambios.
Integración con Kiro
Kiro admite servidores MCP mediante su archivo de configuración dedicado. Hay dos niveles disponibles:
- Global (todos los proyectos):
~/.kiro/settings/mcp.json - Workspace (solo este repositorio):
.kiro/settings/mcp.json
{ "mcpServers": { "facturacion-es": { "command": "uvx", "args": ["mcp-facturacion-electronica-es"], "env": { "AEAT_ENV": "sandbox", "AEAT_CERTIFICATE_PATH": "/ruta/al/cert.p12", "AEAT_CERTIFICATE_PASSWORD": "contrasena-del-certificado" }, "disabled": false, "autoApprove": [] } }}El archivo se recarga automaticamente al guardar. Tambien puede abrir la configuracion desde la paleta de comandos (Cmd+Shift+P / Ctrl+Shift+P) y luego MCP.
Consejo de seguridad de Kiro: en lugar de escribir los secretos en texto plano, use la sintaxis
"AEAT_CERTIFICATE_PASSWORD": "${AEAT_CERTIFICATE_PASSWORD}", Kiro resuelve las variables de entorno de la shell al iniciar.
Herramientas disponibles
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.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice |
InvoiceDocument |
Si | Modelo de factura del core (vendedor, comprador, lineas, IVA) |
previous_hash |
string |
No | SHA-256 Huella del registro precedente (null = primero en la cadena) |
software_id |
string |
Si | IDSistemaInformatico del software certificado |
software_nif |
string |
Si | NIF del fabricante del software |
invoice_type |
string |
Si | F1, F2, R1-R5 o F3 |
{ "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" }}El algoritmo de encadenamiento
Huella(SHA-256 sobre la cadena canonicacampo=valor&con claves) esta confirmado byte a byte contra la especificacion oficial de huella de la AEAT y sus ejemplos resueltos (specs/verifactu/documentation/Veri-Factu_especificaciones_huella_hash_registros.pdf). ⚠️ Pendiente aun: validacion completa del XSD v1.0 contra una confirmacion real del entorno de pruebas 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).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | Registro VERI*FACTU XML en crudo |
schema_version |
string |
No | Version del esquema (por defecto: "1.0") |
{ "tool": "es__validate_verifactu_record", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>" } }Las comprobaciones estructurales ahora distinguen correctamente entre
RegistroAltayRegistroAnulacion(una version anterior marcaba erroneamente documentosRegistroAnulacionvalidos como si les faltaranTipoFactura/CuotaTotal/ImporteTotal, campos que solo aplican aRegistroAlta). La validacion en modo XSD completo (SuministroLR.xsd, incluido enspecs/verifactu/xsd/) requiere acceso a red en tiempo de ejecucion — importa el esquema xmldsig-core de W3C mediante una URL remota — y recurre a las comprobaciones estructurales anteriores cuando esa importacion no puede resolverse.
es__submit_verifactu_to_aeat
Envia un registro VERI*FACTU firmado al endpoint en tiempo real de la AEAT mediante MTLS
(certificado FNMT-RCM Clase 1) o, si EINVOICING_SIGNER_SOCKET esta configurado, a traves del
microservicio de firma. Respeta AEAT_ENV=sandbox|production. El endpoint de envio
(.../SistemaFacturacion/VerifactuSOAP) esta confirmado a partir del WSDL oficial de la AEAT y
es compartido tanto por el envio de alta/anulacion como por la operacion de consulta de
es__query_verifactu_status.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML VERI*FACTU firmado |
nif |
string |
Si | NIF del remitente |
{ "tool": "es__submit_verifactu_to_aeat", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>", "nif": "B12345678" } }La respuesta incluye un objeto chain que implementa el contrato de “encadenar solo lo
aceptado”: chain.safe_to_chain_from (el emisor_nif/num_serie/fecha/huella propios del
registro enviado) solo se rellena cuando el EstadoRegistro de la AEAT es Correcto o
AceptadoConErrores — ambos significan que el registro se almaceno realmente con esa Huella.
En caso contrario, safe_to_chain_from es null con un warning explicito de no usar la
Huella de este registro como previous_hash del siguiente, o (para un resultado deferred)
una note para llamar antes a es__query_verifactu_status.
es__generate_qr_verifactu
Genera el codigo QR obligatorio de VERI*FACTU (HAC/1177/2024 Art. 10) como PNG en base64.
Codifica la URL de verificacion de la AEAT con el texto “Factura verificable en la sede
electronica de la AEAT”. Candidato a promocion a mcp-einvoicing-core (generacion de QR).
El formato de la URL (host, ruta, parametros de consulta nif/numserie/fecha/importe, y
la codificacion URL de cada parametro) esta confirmado contra la especificacion oficial de QR
de la AEAT (specs/verifactu/documentation/DetalleEspecificacTecnCodigoQRfactura.pdf); la URL
cambia entre el host ValidarQR de pruebas y el de produccion segun AEAT_ENV.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
nif |
string |
Si | NIF del emisor |
invoice_number |
string |
Si | NumSerieFactura |
invoice_date |
string |
Si | FechaExpedicionFactura (YYYY-MM-DD) |
total_amount |
number |
Si | Total de la factura con IVA incluido |
size_px |
integer |
No | Tamano del QR en pixeles (por defecto: 200) |
{ "tool": "es__generate_qr_verifactu", "arguments": { "nif": "B12345678", "invoice_number": "2025-0042", "invoice_date": "2025-03-15", "total_amount": 1210.00 } }es__cancel_verifactu_record
Genera un registro de anulacion VERI*FACTU (RegistroAnulacion, TipoHuella=01) encadenado
a la secuencia de huellas actual. Tanto la Huella de anulacion (SHA-256 sobre
IDEmisorFacturaAnulada/NumSerieFacturaAnulada/FechaExpedicionFacturaAnulada/Huella/
FechaHoraHusoGenRegistro — un conjunto de campos distinto al de RegistroAlta, no una copia
reducida del mismo) como los nombres de elemento del bloque <IDFactura> de nivel superior
estan confirmados contra la especificacion oficial de huella de la AEAT y contra
SuministroInformacion.xsd.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
original_invoice_number |
string |
Si | NumSerieFactura a anular |
original_invoice_date |
string |
Si | FechaExpedicionFactura (YYYY-MM-DD) |
issuer_nif |
string |
Si | NIF del emisor |
previous_hash |
string |
Si | Huella del ultimo registro en la cadena |
{ "tool": "es__cancel_verifactu_record", "arguments": { "original_invoice_number": "2025-0042", "original_invoice_date": "2025-03-15", "issuer_nif": "B12345678", "previous_hash": "3C4A9B..." } }es__query_verifactu_status
Consulta el EstadoRegistro de un registro VERI*FACTU ya enviado
(ConsultaFactuSistemaFacturacion / ConsultaLR.xsd). Usar tras un resultado deferred
de es__submit_verifactu_to_aeat: esperar retry_after_seconds, luego llamar a esta tool
para confirmar el estado final (Correcto / AceptadoConErrores / Anulado) antes de
encadenar el siguiente registro. Requiere AEAT_ENV, AEAT_CERTIFICATE_PATH y
AEAT_CERTIFICATE_PASSWORD, igual que es__submit_verifactu_to_aeat.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
nif |
string |
Si | NIF del obligado a la emision |
name |
string |
Si | Nombre/razon social del obligado a la emision |
invoice_date |
string |
Si | Fecha de la factura consultada, YYYY-MM-DD (determina PeriodoImputacion) |
num_serie_factura |
string |
No | Filtro NumSerieFactura (omitir para consultar todo el periodo) |
{ "tool": "es__query_verifactu_status", "arguments": { "nif": "B12345678", "name": "Empresa SL", "invoice_date": "2025-03-15", "num_serie_factura": "2025-0042" } }El nombre del elemento raiz (
ConsultaFactuSistemaFacturacion) y el endpoint — la misma URL.../SistemaFacturacion/VerifactuSOAPque usaes__submit_verifactu_to_aeat, segun el WSDL oficial — estan ambos confirmados. ⚠️ Pendiente aun: el parseo de la respuesta no se ha validado contra una confirmacion real del entorno de pruebas AEAT.
Facturae / FACe
es__generate_facturae_xml
Genera una factura XML conforme a Facturae 3.2.2 para su envio B2G. Utiliza
InvoiceDocument de mcp-einvoicing-core.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice |
InvoiceDocument |
Si | Modelo de factura del core |
schema_version |
string |
No | Version del esquema Facturae (por defecto: "3.2.2") |
tax_type |
string |
No | Regimen de impuesto indirecto: IVA (peninsula/Baleares), IPSI (Ceuta/Melilla) o IGIC (Canarias). No se admite mezclar impuestos en una misma factura. Por defecto: "IVA" |
recargo_equivalencia_rate |
number |
No | Tipo de Recargo de Equivalencia (%), si aplica |
recargo_equivalencia_amount |
number |
No | Importe explicito del Recargo de Equivalencia; si se omite, se calcula como base_imponible * recargo_equivalencia_rate / 100 |
irpf_rate |
number |
No | Tipo de retencion IRPF (%), emitido en TaxesWithheld |
{ "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 confirmacion regulatoria
es__sign_facturae_xades
Aplica una firma digital XAdES-EPES (ETSI EN 319 132-1) a un documento Facturae XML.
Candidato a promocion a mcp-einvoicing-core (firma XAdES, puntuacion 3/3).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML Facturae sin firmar |
cert_path |
string |
Si | Ruta al certificado PKCS#12 (.p12 / .pfx) |
signature_policy_id |
string |
No | OID de la politica de firma (por defecto: estandar Facturae) |
La contrasena del certificado no se acepta como argumento de la tool (ES-SH-6, evita
exponer credenciales en texto plano en el contexto del LLM o en los logs); establecer
AEAT_CERTIFICATE_PASSWORD en su lugar.
{ "tool": "es__sign_facturae_xades", "arguments": { "xml": "<Facturae>...</Facturae>", "cert_path": "/certs/empresa.p12" } }⚠️ Pendiente de confirmacion regulatoria
es__submit_to_face
Envia un XML Facturae firmado a FACe (Punto General de Entrada de Facturas Electronicas)
a traves de la API REST de integradores de FACe. Se autentica con un JWT firmado JWS
(RS256, cabecera x5c) generado a partir del mismo certificado AEAT_CERTIFICATE_PATH /
AEAT_CERTIFICATE_PASSWORD usado para VERI*FACTU/SII, segun
FACe-manual-api-integradores.pdf s2.3.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML Facturae con firma XAdES |
administrative_unit |
string |
Si | Codigo UnidadTramitadora de FACe |
accounting_office |
string |
Si | Codigo OficinasContables de FACe |
management_body |
string |
Si | Codigo OrganoGestor de FACe |
{ "tool": "es__submit_to_face", "arguments": { "xml": "<Facturae>...</Facturae>", "administrative_unit": "U00000038", "accounting_office": "U00000038", "management_body": "U00000038" } }⚠️ Pendiente de confirmacion regulatoria
es__get_face_invoice_status
Consulta el estado de tramitacion de una factura en FACe. Devuelve los codigos estandar:
1200 (Registrada), 2400 (Reconocida), 3100 (Rechazada), 4100 (Pagada). La respuesta cruda
de FACe nunca se muestra al LLM; solo se devuelve un subconjunto estructurado y no sensible
(status_code, codigo, descripcion, numeroRegistro) (ES-SH-7).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice_id |
string |
Si | Numero de registro FACe |
{ "tool": "es__get_face_invoice_status", "arguments": { "invoice_id": "FAC-2025-00012345" } }⚠️ Pendiente de confirmacion 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.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML Facturae a validar |
schema_version |
string |
No | Version del esquema (por defecto: "3.2.2") |
{ "tool": "es__validate_facturae_schema", "arguments": { "xml": "<Facturae>...</Facturae>" } }⚠️ Pendiente de confirmacion regulatoria
SII (Suministro Inmediato de Informacion)
es__build_sii_invoice_record
Construye un registro XML AEAT SII (emision FacturaExpedida o recepcion FacturaRecibida)
conforme a la guia tecnica SII de la AEAT v3.0 (abril 2024). Soporta TipoComunicacion A0/A1/A4.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice |
InvoiceDocument |
Si | Modelo de factura del core |
record_type |
string |
Si | "issued" (emitida) o "received" (recibida) |
communication_type |
string |
No | "A0" alta (por defecto), "A1" modificacion, "A4" baja |
{ "tool": "es__build_sii_invoice_record", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "record_type": "issued", "communication_type": "A0" } }⚠️ Pendiente de confirmacion regulatoria
es__submit_sii_batch
Envia un lote de facturas (maximo 10.000 registros) al endpoint SOAP SII de la AEAT. Requiere MTLS.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
records |
array |
Si | Lista de cadenas XML de es__build_sii_invoice_record |
record_type |
string |
Si | "issued" o "received" |
fiscal_year |
integer |
Si | Ejercicio fiscal (YYYY) |
{ "tool": "es__submit_sii_batch", "arguments": { "records": ["<RegistroLRFacturasEmitidas>...</RegistroLRFacturasEmitidas>"], "record_type": "issued", "fiscal_year": 2025 } }⚠️ Pendiente de confirmacion regulatoria:
AuthMode.MTLSno esta implementado aun enmcp-einvoicing-core.
es__query_sii_status
Consulta el estado de un lote SII enviado mediante ConsultaFactInformadasEmitidas o
ConsultaFactInformadasRecibidas.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
nif_titular |
string |
Si | NIF del titular SII (obligado tributario) |
nombre_titular |
string |
Si | Nombre o razon social del titular |
fiscal_year |
integer |
Si | Ejercicio fiscal (YYYY) |
period |
string |
Si | Periodo de liquidacion: "01".."12" para mensual, o "0A" para anual |
record_type |
string |
No | "issued" o "received" (por defecto: "issued") |
invoice_number |
string |
No | NumSerieFacturaEmisor para filtrar por una factura concreta |
emisor_nif |
string |
No | NIF del emisor para filtrar (solo aplica a "received") |
{ "tool": "es__query_sii_status", "arguments": { "nif_titular": "B12345674", "nombre_titular": "Ejemplo SL", "fiscal_year": 2025, "period": "03", "record_type": "issued" } }⚠️ Pendiente de confirmacion regulatoria
es__generate_sii_correction
Genera un registro de modificacion SII (A1) o baja (A4) que referencia la factura
original mediante IDFactura. El constructor de facturas rectificativas es candidato a
mcp-einvoicing-core (puntuacion 3/3).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
original_invoice |
InvoiceDocument |
Si | Factura que se rectifica |
corrected_invoice |
InvoiceDocument |
No | Datos corregidos (null para A4) |
correction_type |
string |
Si | "A1" o "A4" |
record_type |
string |
Si | "issued" o "received" |
{ "tool": "es__generate_sii_correction", "arguments": { "original_invoice": { "number": "2025-0042" }, "correction_type": "A1", "record_type": "issued" } }⚠️ Pendiente de confirmacion regulatoria
TicketBAI
es__generate_ticketbai_xml
Genera una factura XML TicketBAI con firma XAdES y cadena HuellaTBAI. Selecciona
automaticamente el XSD provincial correcto: Araba v1.2, Gipuzkoa v1.2, Bizkaia v2.1.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice |
InvoiceDocument |
Si | Modelo de factura del core |
province |
string |
Si | "araba", "gipuzkoa" o "bizkaia" |
previous_hash |
string |
No | HuellaTBAI del registro precedente |
software_license |
string |
Si | Clave de licencia del software TicketBAI |
cert_path |
string |
Si | Ruta del certificado de firma |
cert_password |
string |
Si | Contrasena del certificado |
{ "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 confirmacion regulatoria: los tres XSD provinciales deben empaquetarse por separado; no se deben validar cruzadamente entre provincias.
es__submit_ticketbai
Envia un registro TicketBAI XML a la autoridad provincial vasca correspondiente. El endpoint
se enruta automaticamente: Araba (batuz.eus), Gipuzkoa (tbai.egoitza.gipuzkoa.eus),
Bizkaia (www.bizkaia.eus/ogasun).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML TicketBAI firmado |
province |
string |
Si | "araba", "gipuzkoa" o "bizkaia" |
nif |
string |
Si | NIF del remitente |
{ "tool": "es__submit_ticketbai", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "bizkaia", "nif": "B12345678" } }⚠️ Pendiente de confirmacion regulatoria
es__validate_ticketbai_schema
Valida un documento XML TicketBAI contra el XSD provincial correcto. Los esquemas no son intercambiables entre provincias.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | XML TicketBAI |
province |
string |
Si | "araba", "gipuzkoa" o "bizkaia" |
{ "tool": "es__validate_ticketbai_schema", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "gipuzkoa" } }⚠️ Pendiente de confirmacion 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 segun la Ley 18/2022, desarrollada por el RD 238/2026 (BOE-A-2026-7295).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
invoice |
InvoiceDocument |
Si | Modelo de factura del core |
format |
string |
No | "ubl" (por defecto) o "facturae" |
{ "tool": "es__generate_b2b_einvoice_es", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "format": "ubl" } }⚠️ El RD 238/2026 confirma los formatos admitidos (EN 16931: CII/UBL/EDIFACT/Facturae; esta herramienta implementa UBL y Facturae). La Orden Ministerial (Hacienda) que desarrolla el paquete técnico de la solución pública (Disp. final tercera) sigue pendiente.
es__check_b2b_mandate_applicability
Determina el regimen aplicable (VERI*FACTU, SII, TicketBAI, NaTicket) a partir del volumen de operaciones, el codigo de provincia y la inscripcion en el SII. Aplica la logica de exclusion mutua del Real Decreto 254/2025.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
annual_turnover_eur |
number |
Si | Volumen anual de operaciones IVA en EUR |
tax_address_province_code |
string |
Si | Codigo de provincia INE (p. ej., "28" Madrid) |
enrolled_in_sii |
boolean |
No | Inscripcion en el SII (por defecto: false) |
entity_type |
string |
No | "IS" (Impuesto sobre Sociedades) o "IRPF" |
{ "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 confirmacion regulatoria
Herramientas de utilidad
es__detect_regional_regime
Detecta el regimen de facturacion electronica aplicable a partir del codigo de provincia INE.
Devuelve VERIFACTU, TICKETBAI, NATICKET o VERIFACTU+SII.
Provincias vascas: 01 Araba, 20 Gipuzkoa, 48 Bizkaia. Navarra: 31.
El resto devuelve VERIFACTU. Candidato a promocion a mcp-einvoicing-core.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
province_code |
string |
Si | Codigo de provincia INE de dos digitos |
enrolled_in_sii |
boolean |
No | Inscripcion en el SII (por defecto: false) |
{ "tool": "es__detect_regional_regime", "arguments": { "province_code": "20", "enrolled_in_sii": false } }⚠️ Pendiente de confirmacion 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 legislacion posterior.
Candidato a promocion a mcp-einvoicing-core (registro generico de plazos).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
entity_type |
string |
Si | "IS" o "IRPF" |
province_code |
string |
Si | Codigo de provincia INE |
annual_turnover_eur |
number |
No | Para la verificacion del umbral SII (6M EUR) |
enrolled_in_sii |
boolean |
No | Inscripcion en el SII |
{ "tool": "es__get_compliance_status", "arguments": { "entity_type": "IS", "province_code": "28", "annual_turnover_eur": 1000000, "enrolled_in_sii": false } }⚠️ Pendiente de confirmacion 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
(codigo seguro de verificacion) y detalle de errores. Candidato a promocion a
mcp-einvoicing-core (analizador generico de respuestas XML de proveedores, puntuacion 2/3).
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
xml |
string |
Si | Respuesta XML de la AEAT en crudo |
response_type |
string |
No | "verifactu" (por defecto) o "sii" |
{ "tool": "es__parse_aeat_response", "arguments": { "xml": "<RespuestaRegFactuSistemaFacturacion>...</RespuestaRegFactuSistemaFacturacion>", "response_type": "verifactu" } }⚠️ Pendiente de confirmacion regulatoria
Arquitectura
mcp-facturacion-electronica-es es un adaptador de pais 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 (Belgica — Peppol BIS 3.0, PINT-BE, Mercurius)├── mcp-facturacion-electronica-es (Espana — este paquete)│ ├── verifactu/ generacion de registros, cadena hash, QR, anulacion│ ├── facturae/ XML Facturae 3.2.2, XAdES-EPES, envio FACe│ ├── sii/ construccion de lotes, SOAP AEAT, rectificaciones│ ├── ticketbai/ generacion XML, enrutamiento provincial, validacion│ ├── b2b/ UBL/Facturae Crea y Crece, detector de mandato│ └── utils/ deteccion de regimen, analizador respuestas AEAT, registro de plazos├── mcp-fattura-elettronica-it (Italia — FatturaPA / SDI)└── mcp-ksef-pl (Polonia — KSeF / FA(2))Normas admitidas
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; el RD 238/2026
(BOE-A-2026-7295) confirma los formatos admitidos (EN 16931: CII/UBL/EDIFACT/Facturae),
mientras que la Orden Ministerial que desarrolla el paquete técnico de la solución pública
sigue pendiente. 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
| Sistema | Ámbito | Formato | Obligatorio desde | Estado |
|---|---|---|---|---|
| VERI*FACTU | Todas las empresas no-SII | XML propietario (XSD v1.0 HAC/1177/2024) | IS: ene 2027 / Otros: jul 2027 (RD-ley 15/2025) | Implementado (pendiente de confirmacion regulatoria) |
| Facturae / FACe | B2G (sector público) | Facturae 3.2.2 + XAdES-EPES | Obligatorio desde 2015 (Ley 25/2013) | Implementado (pendiente de confirmacion regulatoria) |
| SII | Facturación >6M EUR, grupos IVA, REDEME | XML SOAP/REST AEAT | Ya obligatorio (RD 596/2016) | Implementado (pendiente de confirmacion regulatoria) |
| TicketBAI | Araba, Gipuzkoa, Bizkaia | XML provincial + XAdES + QR | Según provincia, 2022-2023 | Eliminado del alcance (v0.2.0) |
| Crea y Crece (B2B) | Todas las empresas (12/24 meses tras la OM, según facturación) | UBL 2.1 o Facturae 3.2.2 (EN 16931); CII/EDIFACT también admitidos, no implementados | RD 238/2026 publicado; Orden Ministerial (solución pública) pendiente | Implementado (formatos confirmados por RD 238/2026; solución pública pendiente de la OM) |
| NaTicket | Navarra | XML foral + firma | Mandato foral (implantacion escalonada) | Parcial (via es__detect_regional_regime) |
Exclusion mutua SII / VERI*FACTU (Real Decreto 254/2025): Los contribuyentes inscritos en el SII quedan exentos de VERI*FACTU. Utilice
es__check_b2b_mandate_applicabilityantes de generar cualquier registro.
Notas de cumplimiento normativo
Aviso: Las fechas de mandato reflejan el RD-ley 15/2025 (diciembre 2025) y estan sujetas a cambios por legislacion posterior o instrucciones administrativas de la AEAT. Este software no constituye asesoramiento juridico ni fiscal.
Calendario de mandatos
| Sistema | Destinatarios | Plazo |
|---|---|---|
| SII | Facturacion >6M EUR / grupos IVA / REDEME | Ya obligatorio (RD 596/2016) |
| Facturae/FACe | Todos los proveedores B2G | Ya obligatorio (Ley 25/2013) |
| TicketBAI | Todas las empresas del Pais Vasco | Implantacion sectorial 2022-2023 |
| VERI*FACTU | Contribuyentes IS (Impuesto sobre Sociedades) | Enero 2027 (RD-ley 15/2025) |
| VERI*FACTU | IRPF + otros no-SII | Julio 2027 (RD-ley 15/2025) |
| Crea y Crece B2B | Facturacion >8M EUR (art. 121 Ley 37/1992) | 12 meses tras la entrada en vigor de la Orden Ministerial [Fecha no verificada] |
| Crea y Crece B2B | Resto de empresas | 24 meses tras la entrada en vigor de la Orden Ministerial [Fecha no verificada] |
Excepciones regionales
- Pais Vasco: TicketBAI aplica en lugar de VERI*FACTU. Cada una de las tres provincias (Araba, Gipuzkoa, Bizkaia) tiene un XSD, endpoint y proceso de certificacion 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.
- Exclusion mutua SII / VERI*FACTU: El Real Decreto 254/2025 hace estos sistemas mutuamente excluyentes. Los contribuyentes inscritos en el SII no envian registros VERI*FACTU.
Todos los endpoints de envio 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 desarrollouv sync --all-extras
# Ejecutar la suite de tests completauv run pytest tests/ -v
# Con informe de coberturauv run pytest --cov=mcp_facturacion_electronica_es --cov-report=term-missingContribuir
Abra un issue antes de iniciar trabajo significativo. Para logica de utilidad reutilizable
entre adaptadores de pais, abra un issue de core-promotion en mcp-einvoicing-core antes
de implementarla: utilice la rubrica de puntuacion (3 = DEBE promoverse, 2 = DEBERIA, 1 = mantener aqui).
git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.gitcd mcp-facturacion-electronica-esuv sync --all-extrasuv run pytestmake auditTodas las afirmaciones regulatorias deben referenciar una publicacion especifica del BOE,
una version oficial del XSD o una version de la guia tecnica de la AEAT. No elimine
⚠️ Pendiente de confirmacion regulatoria sin enlazar la fuente verificada en la
descripcion del PR.
Otros servidores MCP de facturación electrónica
| País | Servidor |
|---|---|
| 🌍 Global | mcp-einvoicing-core |
| 🇧🇪 Bélgica | mcp-einvoicing-be |
| 🇧🇷 Brasil | mcp-nfe-br |
| 🇫🇷 Francia | mcp-facture-electronique-fr |
| 🇩🇪 Alemania | mcp-einvoicing-de |
| 🇮🇹 Italia | mcp-fattura-elettronica-it |
| 🇲🇽 México | mcp-cfdi-mx |
| 🇵🇱 Polonia | mcp-ksef-pl |
| 🇸🇬 Singapur | mcp-invoicenow-sg |
| 🇪🇸 España | mcp-facturacion-electronica-es |
| 🇦🇪 Emiratos Árabes Unidos | mcp-einvoicing-ae |
Licencia
Publicado bajo la licencia Apache 2.0. Para el historial completo de versiones, vea CHANGELOG.md.