mcp-facturacion-electronica-es 🇪🇸
English | Espanol
[License]
[PyPI version]
[Python] [mcp-facturacion-electronica-es MCP server]
Introduction
mcp-facturacion-electronica-es is an MCP (Model Context Protocol) server specialized
in Spanish e-invoicing. It provides tools to generate, validate, and submit electronic
invoices under the six coexisting systems in Spain: VERI*FACTU, Facturae/FACe,
SII, TicketBAI (Basque Country), NaTicket (Navarre), and the B2B obligations of Ley 18/2022
"Crea y Crece". The server is built on mcp-einvoicing-core,
the shared base library used by mcp-facture-electronique-fr (France, XP Z12-013) and
mcp-einvoicing-be (Belgium, Peppol BIS 3.0), which provides common models, validation
abstractions, XML utilities, and the exception hierarchy. mcp-einvoicing-core is installed
automatically as a transitive dependency, no additional steps are required.
Spain operates one of the most complex e-invoicing landscapes in Europe, with six overlapping
systems that 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 Informacion, Immediate Information Supply) already applies to
large taxpayers (>6M EUR 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).
Installation
From PyPI (recommended)
Without prior installation, using uvx:
From source
Configuration
All configuration is done through environment variables or a .env file.
AEAT / VERI*FACTU / SII
FACe
FACe authenticates via JWS using the same AEAT_CERTIFICATE_PATH / AEAT_CERTIFICATE_PASSWORD
certificate as VERI*FACTU/SII (see the AEAT section above); no separate FACe credentials are
required.
Common (inherited from mcp-einvoicing-core)
Claude Desktop integration
To use this server with Claude, add this configuration to your claude_desktop_config.json file:
Cursor integration
Cursor supports MCP servers via stdio. Add the configuration in:
- Global (all projects):
~/.cursor/mcp.json
- Project (this repository only):
.cursor/mcp.json
Reload the Cursor window (Ctrl+Shift+P then Reload Window) to apply the changes.
Kiro integration
Kiro supports MCP servers via its dedicated configuration file. Two levels are available:
- Global (all projects):
~/.kiro/settings/mcp.json
- Workspace (this repository only):
.kiro/settings/mcp.json
The file is automatically reloaded on save. You can also open the config via the command palette (Cmd+Shift+P / Ctrl+Shift+P) then MCP.
Kiro security tip: rather than writing secrets in plain text, use the syntax "AEAT_CERTIFICATE_PASSWORD": "${AEAT_CERTIFICATE_PASSWORD}", Kiro resolves shell environment variables at startup.
Available tools
VERI*FACTU
es__generate_verifactu_record
Generates a tamper-proof invoice record (Orden HAC/1177/2024) with SHA-256 Huella
chaining that links it to the previous record.
The Huella chaining algorithm (SHA-256 over the keyed campo=valor& canonical string) is
confirmed byte-for-byte against AEAT's own huella specification and its worked examples
(specs/verifactu/documentation/Veri-Factu_especificaciones_huella_hash_registros.pdf).
Generated records validate against the bundled XSD v1.0 (SuministroLR and SuministroInformacion, with
the W3C XML-DSig schema resolved locally). ⚠️ Still pending: a live AEAT test-environment acknowledgement.
es__validate_verifactu_record
Validates a VERI*FACTU XML record against the official XSD published with Orden HAC/1177/2024
(BOE-A-2024-22138).
Structural checks now branch correctly on RegistroAlta vs. RegistroAnulacion (a prior version
false-flagged valid RegistroAnulacion documents as missing TipoFactura/CuotaTotal/ImporteTotal,
fields that only apply to RegistroAlta). Full XSD-mode validation (SuministroLR.xsd, bundled
under resources/verifactu/) requires network access at runtime — it imports the W3C xmldsig-core
schema by remote URL — and falls back to the structural checks above when that import can't
resolve.
es__submit_verifactu_to_aeat
Submits a signed VERI*FACTU record to the AEAT real-time endpoint via MTLS
(FNMT-RCM Class 1 certificate) or, if EINVOICING_SIGNER_SOCKET is configured, via the
signer microservice. Respects AEAT_ENV=sandbox|production. The submission endpoint
(.../SistemaFacturacion/VerifactuSOAP) is confirmed from the official AEAT WSDL and shared
by both the alta/anulación submission and the es__query_verifactu_status query operation.
The response includes a chain object implementing the accepted-only chain contract:
chain.safe_to_chain_from (the submitted record's own emisor_nif/num_serie/fecha/huella)
is populated only when AEAT's EstadoRegistro is Correcto or AceptadoConErrores — both mean
the record was actually stored under that Huella. Otherwise safe_to_chain_from is null with
an explicit warning not to use this record's Huella as the next record's previous_hash, or
(for a deferred result) a note to call es__query_verifactu_status first.
es__generate_qr_verifactu
Generates the mandatory VERI*FACTU QR code (HAC/1177/2024 Art. 10) as a base64-encoded PNG.
Encodes the AEAT verification URL with the text "Factura verificable en la sede
electronica de la AEAT". Candidate for promotion to mcp-einvoicing-core (QR generation).
URL format (host, path, nif/numserie/fecha/importe query parameters, and per-parameter
URL-encoding) is confirmed against the official AEAT QR specification
(specs/verifactu/documentation/DetalleEspecificacTecnCodigoQRfactura.pdf); the URL switches
between the sandbox and production ValidarQR host based on AEAT_ENV.
es__cancel_verifactu_record
Generates a VERI*FACTU cancellation record (RegistroAnulacion, TipoHuella=01) chained to
the current fingerprint sequence. Both the anulación Huella (SHA-256 over
IDEmisorFacturaAnulada/NumSerieFacturaAnulada/FechaExpedicionFacturaAnulada/Huella/
FechaHoraHusoGenRegistro — a distinct field set from RegistroAlta's, not a reduced copy of
it) and the top-level <IDFactura> block's element names are confirmed against the official AEAT
huella specification and SuministroInformacion.xsd.
es__query_verifactu_status
Queries the EstadoRegistro of an already-submitted VERI*FACTU record
(ConsultaFactuSistemaFacturacion / ConsultaLR.xsd). Use after a deferred result from
es__submit_verifactu_to_aeat: wait retry_after_seconds, then call this tool to confirm
the final state (Correcto / AceptadoConErrores / Anulado) before chaining the next
record. Requires AEAT_ENV, AEAT_CERTIFICATE_PATH, and AEAT_CERTIFICATE_PASSWORD, same
as es__submit_verifactu_to_aeat.
Root element name (ConsultaFactuSistemaFacturacion) and endpoint — the same
.../SistemaFacturacion/VerifactuSOAP URL used by es__submit_verifactu_to_aeat, per the
official WSDL — are both confirmed. ⚠️ Still pending: response parsing has not been validated
against a live AEAT sandbox acknowledgement.
Facturae / FACe
es__generate_facturae_xml
Generates a Facturae 3.2.2 compliant XML invoice for B2G submission. Uses
InvoiceDocument from mcp-einvoicing-core.
⚠️ Pending regulatory confirmation
es__sign_facturae_xades
Applies an XAdES-EPES digital signature (ETSI EN 319 132-1) to a Facturae XML document.
Candidate for promotion to mcp-einvoicing-core (XAdES signing, score 3/3).
The certificate password is not accepted as a tool argument (ES-SH-6, avoids plaintext
credential exposure in LLM context/logs); set AEAT_CERTIFICATE_PASSWORD instead.
⚠️ Pending regulatory confirmation
es__submit_to_face
Submits a signed Facturae XML to FACe (Punto General de Entrada de Facturas Electronicas)
via the FACe integrator REST API. Authenticates with a JWS-signed JWT (RS256, x5c header)
minted from the same AEAT_CERTIFICATE_PATH / AEAT_CERTIFICATE_PASSWORD certificate used
for VERI*FACTU/SII, per FACe-manual-api-integradores.pdf s2.3.
⚠️ Pending regulatory confirmation
es__get_face_invoice_status
Queries the processing status of an invoice on FACe. Returns standard status codes:
1200 (Registered), 2400 (Acknowledged), 3100 (Rejected), 4100 (Paid). The raw FACe
response is never echoed to the LLM; only a structured, non-sensitive subset
(status_code, codigo, descripcion, numeroRegistro) is returned (ES-SH-7).
⚠️ Pending regulatory confirmation
es__validate_facturae_schema
Runs the structural field checklist against a Facturae XML, then attempts full XSD-mode
validation against the official Facturae 3.2.2 schema using lxml.
Full XSD-mode validation (Facturaev3_2_2.xml, bundled under resources/facturae/) requires
network access at runtime — it imports the W3C xmldsig-core schema by remote URL — and falls
back to the structural checks above when that import can't resolve.
⚠️ Pending regulatory confirmation
SII (Suministro Inmediato de Informacion)
es__build_sii_invoice_record
Builds an AEAT SII XML record (issued FacturaExpedida or received FacturaRecibida)
conforming to the AEAT SII technical guide v3.0 (April 2024). Supports TipoComunicacion A0/A1/A4.
⚠️ Pending regulatory confirmation
es__submit_sii_batch
Submits a batch of invoices (up to 10,000 records) to the AEAT SII SOAP endpoint. Requires MTLS.
⚠️ Pending regulatory confirmation: AuthMode.MTLS is not yet implemented in mcp-einvoicing-core.
es__query_sii_status
Queries the status of a submitted SII batch via ConsultaFactInformadasEmitidas or
ConsultaFactInformadasRecibidas.
⚠️ Pending regulatory confirmation
es__generate_sii_correction
Generates an SII modification (A1) or cancellation (A4) record referencing the original
invoice via IDFactura. The credit note builder is a candidate for mcp-einvoicing-core
(score 3/3).
⚠️ Pending regulatory confirmation
Crea y Crece / B2B
es__generate_b2b_einvoice_es
Generates a B2B invoice conforming to EN 16931 in UBL (AEAT public solution profile) or
Facturae 3.2.2 format per Ley 18/2022, developed by RD 238/2026 (BOE-A-2026-7295).
⚠️ RD 238/2026 confirms the admitted formats (EN 16931: CII/UBL/EDIFACT/Facturae; this
tool implements UBL and Facturae). Orden HAC/1028/2026 (BOE-A-2026-20587, in force
2026-10-06) regulates the public e-invoicing solution. The UBL output follows Annex I
(BT-23 and BT-24 values, NIF/NIF-IVA party identification, mandatory postal address) and
validates against the OASIS UBL 2.5 schema; it covers an ordinary type 380 invoice with
one S VAT category per line and none of the Spanish BG-ES groups. The AEAT Schematron
rules for EN 16931:2026 are not published, so they are not run [Unverified].
es__check_b2b_mandate_applicability reports the application dates (2027-10-06 for
taxpayers above €8M, 2028-10-06 for all others).
es__check_b2b_mandate_applicability
Determines the applicable regime (VERI*FACTU or SII) based on turnover, province
code, and SII enrollment. Foral provinces (TicketBAI, NaTicket) are flagged as out of scope. Applies the mutual exclusion logic of
Real Decreto 254/2025.
⚠️ Pending regulatory confirmation
Utility tools
es__detect_regional_regime
Detects the applicable e-invoicing regime based on the INE province code.
Returns VERIFACTU or VERIFACTU+SII.
For the foral provinces (01 Araba, 20 Gipuzkoa, 48 Bizkaia, 31 Navarre), whose TicketBAI and
NaTicket systems are out of scope for this package, the response also carries an
out_of_scope_warning. All other provinces return VERIFACTU without a warning. Candidate for promotion to mcp-einvoicing-core.
⚠️ Pending regulatory confirmation
es__get_compliance_status
Returns the current mandate deadlines and operating system for a business profile.
Reflects RD-ley 15/2025, subject to changes by subsequent legislation.
Candidate for promotion to mcp-einvoicing-core (generic deadline registry).
⚠️ Pending regulatory confirmation
es__parse_aeat_response
Parses and normalizes an AEAT XML response (VERI*FACTU or SII) into structured JSON.
Extracts EstadoEnvio (Correcto/AceptadoConErrores/Incorrecto), CSV
(secure verification code), and error details. Candidate for promotion to
mcp-einvoicing-core (generic vendor XML response parser, score 2/3).
⚠️ Pending regulatory confirmation
Architecture
mcp-facturacion-electronica-es is a country adapter within the mcp-einvoicing family,
built on mcp-einvoicing-core.
Vendor neutrality
This server implements the standard itself: it builds, validates, and signs the document
locally. It is not a client for a commercial invoicing platform, and your signing keys and
credentials never leave your own infrastructure.
Records and invoices go directly to the tax authority — the AEAT (SII, VeriFactu) or FACe —
using your own certificate; no intermediary is involved.
Supported standards
The Spanish e-invoicing ecosystem has six coexisting systems with distinct scopes,
formats, and timelines. VERI*FACTU introduces tamper-proof chained invoice records
submitted in real time to the AEAT (Agencia Estatal de Administracion Tributaria),
applicable to most businesses from 2027 (RD-ley 15/2025). SII is already mandatory for
large taxpayers under a 4-day communication window. Facturae XML with XAdES-EPES signing
covers all B2G invoicing through the FACe portal. The Basque Country applies TicketBAI
independently, with three provincial authorities each maintaining their own XSD schemas and
endpoints. Navarre operates NaTicket. The Ley Crea y Crece mandates B2B e-invoicing for
all businesses; RD 238/2026 (BOE-A-2026-7295) confirms the admitted formats (EN 16931:
CII/UBL/EDIFACT/Facturae), and Orden HAC/1028/2026 regulates the public e-invoicing
solution (UBL output follows its Annex I; the AEAT Schematron rules are not yet published). Regime detection
based on tax domicile and turnover is a prerequisite to all other operations: use
es__detect_regional_regime first.
Regulatory coverage
SII / VERI*FACTU mutual exclusion (Real Decreto 254/2025): Taxpayers enrolled in
SII are exempt from VERI*FACTU. Use es__check_b2b_mandate_applicability
before generating any record.
Compliance notes
Notice: Mandate dates reflect RD-ley 15/2025 (December 2025) and are
subject to changes by subsequent legislation or AEAT administrative instructions.
This software does not constitute legal or tax advice.
Mandate timeline
Regional exceptions
- Basque Country: TicketBAI applies instead of VERI*FACTU.
Each of the three provinces (Araba, Gipuzkoa, Bizkaia) has a different XSD, endpoint,
and software certification process. National AEAT endpoints do not apply.
- Navarre: NaTicket applies (Hacienda Foral de Navarra). VERI*FACTU does not apply.
- Ceuta / Melilla: IPSI (not VAT); SII/VERI*FACTU applicability differs, verify with the AEAT.
- SII / VERI*FACTU mutual exclusion: Real Decreto 254/2025 makes these systems
mutually exclusive. Taxpayers enrolled in SII do not submit VERI*FACTU records.
All AEAT submission endpoints require an FNMT-RCM certificate or one from an accredited CA.
The AEAT provides a free test environment at prewww2.aeat.es.
Tests
Contributing
Open an issue before starting significant work. For reusable utility logic across country
adapters, open a core-promotion issue in mcp-einvoicing-core before implementing it:
use the scoring rubric (3 = MUST promote, 2 = SHOULD, 1 = keep here).
All regulatory assertions must reference a specific BOE publication, an official XSD version,
or an AEAT technical guide version. Do not remove
⚠️ Pending regulatory confirmation without linking the verified source in the
PR description.
Other e-invoicing MCP servers
License
Released under the Apache License 2.0. For the full version history, see CHANGELOG.md.