Skip to main content
Glama
mcp-facturacion-electronica-es

mcp-facturacion-electronica-es

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).

Related MCP server: mcp-facture-electronique-fr

Installation

pip install mcp-facturacion-electronica-es

Without prior installation, using uvx:

uvx mcp-facturacion-electronica-es

From source

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

Configuration

All configuration is done through environment variables or a .env file.

AEAT / VERI*FACTU / SII

Variable

Description

Required

AEAT_ENV

sandbox or production

Yes

AEAT_CERTIFICATE_PATH

Path to FNMT-RCM PKCS#12 certificate

For submission

AEAT_CERTIFICATE_PASSWORD

Certificate password

For submission

AEAT_NIF

Taxpayer NIF

For submission

FACe

Variable

Description

Required

FACE_ENV

sandbox or production

Yes

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.

TicketBAI

Variable

Description

Required

TICKETBAI_ENV

sandbox or production

Yes

TICKETBAI_CERTIFICATE_PATH

Provincial signing certificate path

Yes

TICKETBAI_CERTIFICATE_PASSWORD

Certificate password

Yes

Common (inherited from mcp-einvoicing-core)

Variable

Description

Default

LOG_LEVEL

DEBUG, INFO, WARNING, ERROR

INFO

Claude Desktop integration

To use this server with Claude, add this configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      }
    }
  }
}

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

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      }
    }
  }
}

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

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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.

Parameter

Type

Required

Description

invoice

InvoiceDocument

Yes

Core invoice model (seller, buyer, lines, VAT)

previous_hash

string

No

SHA-256 Huella of the preceding record (null = first in chain)

software_id

string

Yes

IDSistemaInformatico of the certified software

software_nif

string

Yes

NIF of the software manufacturer

invoice_type

string

Yes

F1, F2, R1-R5 or 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"
  }
}

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). ⚠️ Still pending: full XSD v1.0 validation against 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).

Parameter

Type

Required

Description

xml

string

Yes

Raw VERI*FACTU XML record

schema_version

string

No

Schema version (default: "1.0")

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

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.

Parameter

Type

Required

Description

xml

string

Yes

Signed VERI*FACTU XML

nif

string

Yes

Sender NIF

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

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.

Parameter

Type

Required

Description

nif

string

Yes

Issuer NIF

invoice_number

string

Yes

NumSerieFactura

invoice_date

string

Yes

FechaExpedicionFactura (YYYY-MM-DD)

total_amount

number

Yes

Invoice total including VAT

size_px

integer

No

QR size in pixels (default: 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

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.

Parameter

Type

Required

Description

original_invoice_number

string

Yes

NumSerieFactura to cancel

original_invoice_date

string

Yes

FechaExpedicionFactura (YYYY-MM-DD)

issuer_nif

string

Yes

Issuer NIF

previous_hash

string

Yes

Huella of the last record in the chain

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

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.

Parameter

Type

Required

Description

nif

string

Yes

NIF of the ObligadoEmision

name

string

Yes

Name/razĂłn social of the ObligadoEmision

invoice_date

string

Yes

Invoice date being queried, YYYY-MM-DD (determines PeriodoImputacion)

num_serie_factura

string

No

NumSerieFactura filter (omit to query the whole period)

{ "tool": "es__query_verifactu_status", "arguments": { "nif": "B12345678", "name": "Empresa SL", "invoice_date": "2025-03-15", "num_serie_factura": "2025-0042" } }

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.

Parameter

Type

Required

Description

invoice

InvoiceDocument

Yes

Core invoice model

schema_version

string

No

Facturae schema version (default: "3.2.2")

tax_type

string

No

Indirect tax regime: IVA (peninsula/Baleares), IPSI (Ceuta/Melilla), or IGIC (Canarias). Mixing tax types on one invoice is not supported. Default: "IVA"

recargo_equivalencia_rate

number

No

Recargo de Equivalencia rate (%), if applicable

recargo_equivalencia_amount

number

No

Explicit Recargo de Equivalencia amount; if omitted, computed as base_imponible * recargo_equivalencia_rate / 100

irpf_rate

number

No

IRPF withholding rate (%), emitted in 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 }] } } }

⚠️ 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).

Parameter

Type

Required

Description

xml

string

Yes

Unsigned Facturae XML

cert_path

string

Yes

Path to PKCS#12 certificate (.p12 / .pfx)

signature_policy_id

string

No

Signature policy OID (default: Facturae standard)

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.

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

⚠️ 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.

Parameter

Type

Required

Description

xml

string

Yes

Facturae XML with XAdES signature

administrative_unit

string

Yes

FACe UnidadTramitadora code

accounting_office

string

Yes

FACe OficinasContables code

management_body

string

Yes

FACe OrganoGestor code

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

⚠️ 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).

Parameter

Type

Required

Description

invoice_id

string

Yes

FACe registration number

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

⚠️ 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.

Parameter

Type

Required

Description

xml

string

Yes

Facturae XML to validate

schema_version

string

No

Schema version (default: "3.2.2")

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

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.

Parameter

Type

Required

Description

invoice

InvoiceDocument

Yes

Core invoice model

record_type

string

Yes

"issued" or "received"

communication_type

string

No

"A0" new (default), "A1" modification, "A4" cancellation

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

⚠️ 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.

Parameter

Type

Required

Description

records

array

Yes

List of XML strings from es__build_sii_invoice_record

record_type

string

Yes

"issued" or "received"

fiscal_year

integer

Yes

Fiscal year (YYYY)

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

⚠️ 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.

Parameter

Type

Required

Description

nif_titular

string

Yes

NIF of the SII titular (obligado tributario)

nombre_titular

string

Yes

Name or company name of the titular

fiscal_year

integer

Yes

Fiscal year (YYYY)

period

string

Yes

Settlement period: "01".."12" for monthly, or "0A" for annual

record_type

string

No

"issued" or "received" (default: "issued")

invoice_number

string

No

NumSerieFacturaEmisor to filter by a specific invoice

emisor_nif

string

No

Issuer NIF to filter by (only applies to "received")

{ "tool": "es__query_sii_status", "arguments": { "nif_titular": "B12345674", "nombre_titular": "Ejemplo SL", "fiscal_year": 2025, "period": "03", "record_type": "issued" } }

⚠️ 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).

Parameter

Type

Required

Description

original_invoice

InvoiceDocument

Yes

Invoice being corrected

corrected_invoice

InvoiceDocument

No

Corrected data (null for A4)

correction_type

string

Yes

"A1" or "A4"

record_type

string

Yes

"issued" or "received"

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

⚠️ Pending regulatory confirmation


TicketBAI

es__generate_ticketbai_xml

Generates a TicketBAI XML invoice with XAdES signature and HuellaTBAI chain. Automatically selects the correct provincial XSD: Araba v1.2, Gipuzkoa v1.2, Bizkaia v2.1.

Parameter

Type

Required

Description

invoice

InvoiceDocument

Yes

Core invoice model

province

string

Yes

"araba", "gipuzkoa" or "bizkaia"

previous_hash

string

No

HuellaTBAI of the preceding record

software_license

string

Yes

TicketBAI software license key

cert_path

string

Yes

Signing certificate path

cert_password

string

Yes

Certificate password

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

⚠️ Pending regulatory confirmation: the three provincial XSDs must be packaged separately; cross-province validation is not permitted.


es__submit_ticketbai

Submits a TicketBAI XML record to the corresponding Basque provincial authority. The endpoint is automatically routed: Araba (batuz.eus), Gipuzkoa (tbai.egoitza.gipuzkoa.eus), Bizkaia (www.bizkaia.eus/ogasun).

Parameter

Type

Required

Description

xml

string

Yes

Signed TicketBAI XML

province

string

Yes

"araba", "gipuzkoa" or "bizkaia"

nif

string

Yes

Sender NIF

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

⚠️ Pending regulatory confirmation


es__validate_ticketbai_schema

Validates a TicketBAI XML document against the correct provincial XSD. The schemas are not interchangeable between provinces.

Parameter

Type

Required

Description

xml

string

Yes

TicketBAI XML

province

string

Yes

"araba", "gipuzkoa" or "bizkaia"

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

⚠️ Pending regulatory confirmation


Crea y Crece / B2B

es__generate_b2b_einvoice_es

Generates a B2B invoice conforming to EN 16931 in UBL 2.1 or Facturae 3.2.2 format per Ley 18/2022, developed by RD 238/2026 (BOE-A-2026-7295).

Parameter

Type

Required

Description

invoice

InvoiceDocument

Yes

Core invoice model

format

string

No

"ubl" (default) or "facturae"

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

⚠️ 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; this generator does not yet follow its UBL structure because the AEAT electronic-office technical specifications are still pending. 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, SII, TicketBAI, NaTicket) based on turnover, province code, and SII enrollment. Applies the mutual exclusion logic of Real Decreto 254/2025.

Parameter

Type

Required

Description

annual_turnover_eur

number

Yes

Annual VAT turnover in EUR

tax_address_province_code

string

Yes

INE province code (e.g., "28" Madrid)

enrolled_in_sii

boolean

No

SII enrollment (default: false)

entity_type

string

No

"IS" (Impuesto sobre Sociedades) or "IRPF"

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

⚠️ Pending regulatory confirmation


Utility tools

es__detect_regional_regime

Detects the applicable e-invoicing regime based on the INE province code. Returns VERIFACTU, TICKETBAI, NATICKET, or VERIFACTU+SII.

Basque provinces: 01 Araba, 20 Gipuzkoa, 48 Bizkaia. Navarre: 31. All others return VERIFACTU. Candidate for promotion to mcp-einvoicing-core.

Parameter

Type

Required

Description

province_code

string

Yes

Two-digit INE province code

enrolled_in_sii

boolean

No

SII enrollment (default: false)

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

⚠️ 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).

Parameter

Type

Required

Description

entity_type

string

Yes

"IS" or "IRPF"

province_code

string

Yes

INE province code

annual_turnover_eur

number

No

For SII threshold check (6M EUR)

enrolled_in_sii

boolean

No

SII enrollment

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

⚠️ 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).

Parameter

Type

Required

Description

xml

string

Yes

Raw AEAT XML response

response_type

string

No

"verifactu" (default) or "sii"

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

⚠️ Pending regulatory confirmation

Architecture

mcp-facturacion-electronica-es is a country adapter within the mcp-einvoicing family, built on 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    (France — XP Z12-013, Chorus Pro)
├── mcp-einvoicing-be              (Belgium — Peppol BIS 3.0, PINT-BE, Mercurius)
├── mcp-facturacion-electronica-es (Spain — this package)
│   ├── verifactu/   record generation, hash chain, QR, cancellation
│   ├── facturae/    Facturae 3.2.2 XML, XAdES-EPES, FACe submission
│   ├── sii/         batch building, AEAT SOAP, corrections
│   ├── ticketbai/   XML generation, provincial routing, validation
│   ├── b2b/         UBL/Facturae Crea y Crece, mandate detector
│   └── utils/       regime detection, AEAT response parser, deadline registry
├── mcp-fattura-elettronica-it     (Italy — FatturaPA / SDI)
└── mcp-ksef-pl                    (Poland — KSeF / FA(2))

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), FACe, or the relevant provincial TicketBAI platform — 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 (AEAT technical specifications still pending). Regime detection based on tax domicile and turnover is a prerequisite to all other operations: use es__detect_regional_regime first.

Regulatory coverage

System

Scope

Format

Mandatory from

Status

VERI*FACTU

All non-SII businesses

Proprietary XML (XSD v1.0 HAC/1177/2024)

IS: Jan 2027 / Others: Jul 2027 (RD-ley 15/2025)

Implemented (pending regulatory confirmation)

Facturae / FACe

B2G (public sector)

Facturae 3.2.2 + XAdES-EPES

Mandatory since 2015 (Ley 25/2013)

Implemented (pending regulatory confirmation)

SII

Turnover >6M EUR, VAT groups, REDEME

XML SOAP/REST AEAT

Already mandatory (RD 596/2016)

Implemented (pending regulatory confirmation)

TicketBAI

Araba, Gipuzkoa, Bizkaia

Provincial XML + XAdES + QR

By province, 2022-2023

Removed from scope (v0.2.0)

Crea y Crece (B2B)

All businesses (12/24 months after OM, by turnover)

UBL 2.1 or Facturae 3.2.2 (EN 16931); CII/EDIFACT also admitted, not implemented

RD 238/2026 published; Orden Ministerial (public solution) pending

Implemented (formats confirmed by RD 238/2026; public-solution wiring deferred to OM)

NaTicket

Navarre

Foral XML + signature

Foral mandate (phased rollout)

Partial (via es__detect_regional_regime)

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

System

Targets

Deadline

SII

Turnover >6M EUR / VAT groups / REDEME

Already mandatory (RD 596/2016)

Facturae/FACe

All B2G suppliers

Already mandatory (Ley 25/2013)

TicketBAI

All businesses in the Basque Country

Phased rollout by sector 2022-2023

VERI*FACTU

IS (Impuesto sobre Sociedades) taxpayers

January 2027 (RD-ley 15/2025)

VERI*FACTU

IRPF + other non-SII

July 2027 (RD-ley 15/2025)

Crea y Crece B2B

Turnover >8M EUR (art. 121 Ley 37/1992)

12 months after the Orden Ministerial's entry into force [Unverified date]

Crea y Crece B2B

All other businesses

24 months after the Orden Ministerial's entry into force [Unverified date]

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

# Install development dependencies
uv sync --all-extras

# Run the full test suite
uv run pytest tests/ -v

# With coverage report
uv run pytest --cov=mcp_facturacion_electronica_es --cov-report=term-missing

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).

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

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

Country

Server

🌍 Global

mcp-einvoicing-core

🇧🇪 Belgium

mcp-einvoicing-be

🇧🇷 Brazil

mcp-nfe-br

🇫🇷 France

mcp-facture-electronique-fr

🇩🇪 Germany

mcp-einvoicing-de

🇮🇳 India

mcp-einvoicing-in

🇮🇹 Italy

mcp-fattura-elettronica-it

🇲🇽 Mexico

mcp-cfdi-mx

🇵🇱 Poland

mcp-ksef-pl

🇸🇬 Singapore

mcp-invoicenow-sg

🇪🇸 Spain

mcp-facturacion-electronica-es

🇦🇪 United Arab Emirates

mcp-einvoicing-ae

License

Released under the Apache License 2.0. For the full version history, see CHANGELOG.md.

Available Tools

20 tools
es__build_sii_invoice_recordEs Build Sii Invoice RecordB

Construye un registro XML AEAT SII en formato SOAP.

Emisión FacturaExpedida o recepción FacturaRecibida, conforme a la guía técnica SII v3.0 (abril 2024). Soporta TipoComunicacion A0 (alta), A1 (modificación) y A4 (baja).

Inputs: invoice (required), record_type (required), clave_regimen, communication_type. Returns: object

es__cancel_verifactu_recordEs Cancel Verifactu RecordA

Genera un registro de anulacion VERI*FACTU (TipoHuella=01).

Encadenado a la secuencia de huellas actual.

Inputs: issuer_nif (required), issuer_name (required), previous_hash (required), original_invoice_date (required), +4 more. Returns: object

es__check_b2b_mandate_applicabilityEs Check B2B Mandate ApplicabilityA

Determina el régimen de facturación electrónica aplicable.

VERI*FACTU, SII, TicketBAI, NaTicket, a partir del volumen de operaciones, cĂłdigo de provincia y enrolamiento en SII. Aplica la lĂłgica de exclusiĂłn mutua del Real Decreto 254/2025.

Inputs: annual_turnover_eur (required), tax_address_province_code (required), entity_type, enrolled_in_sii. Returns: object

es__detect_regional_regimeEs Detect Regional RegimeA

Detecta el régimen de facturación electrónica aplicable.

A partir del cĂłdigo de provincia INE de dos dĂ­gitos. Devuelve VERIFACTU, TICKETBAI, NATICKET o VERIFACTU+SII. Usar siempre antes de llamar a cualquier otra herramienta de este servidor.

Inputs: province_code (required), enrolled_in_sii. Returns: object

es__generate_b2b_einvoice_esEs Generate B2B Einvoice EsB

Genera una factura B2B conforme a EN 16931 en formato UBL 2.1 o Facturae 3.2.2.

Según la Ley 18/2022 'Crea y Crece'. RD 238/2026 publicado; formatos confirmados (EN 16931: CII/UBL/EDIFACT/Facturae). Orden HAC/1028/2026 regula la solución pública; las especificaciones técnicas de la AEAT están pendientes.

Inputs: invoice (required), format. Returns: object

es__generate_facturae_xmlEs Generate Facturae XmlA

Genera una factura XML conforme a Facturae 3.2.2 para envĂ­o B2G al portal FACe.

El documento generado está sin firmar; use es__sign_facturae_xades para firmarlo.

Inputs: invoice (required), tax_type, irpf_rate, irpf_amount, +6 more. Returns: object

es__generate_qr_verifactuEs Generate Qr VerifactuA

Genera el cĂłdigo QR obligatorio VERI*FACTU (HAC/1177/2024 Art. 10) como PNG en base64.

Encodes la URL de verificaciĂłn de la AEAT: https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?...

Inputs: nif (required), invoice_date (required), total_amount (required), invoice_number (required), +1 more. Returns: object

es__generate_sii_correctionEs Generate Sii CorrectionA

Genera un registro de modificaciĂłn SII (A1) o baja (A4).

Referencia la factura original mediante IDFactura.

Inputs: record_type (required), correction_type (required), original_invoice (required), corrected_invoice. Returns: object

es__generate_verifactu_recordEs Generate Verifactu RecordA

Genera un registro de factura VERI*FACTU (Orden HAC/1177/2024) con cadena SHA-256 Huella.

Devuelve el XML del registro y la Huella para encadenar con el siguiente registro. Llame a es__detect_regional_regime antes para confirmar que el régimen es VERIFACTU.

Inputs: invoice (required), software_id (required), software_nif (required), impuesto, +7 more. Returns: object

es__get_compliance_statusEs Get Compliance StatusC

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.

Inputs: entity_type (required), province_code (required), enrolled_in_sii, annual_turnover_eur. Returns: object

es__get_face_invoice_statusEs Get Face Invoice StatusB

Consulta el estado de tramitaciĂłn de una factura en FACe.

CĂłdigos: 1200 Registrada, 2400 Reconocida, 3100 Rechazada, 4100 Pagada.

Inputs: invoice_id (required). Returns: object

es__parse_aeat_responseEs Parse Aeat ResponseA

Analiza y normaliza una respuesta XML de la AEAT (VERI*FACTU o SII) a JSON estructurado.

Extrae EstadoEnvio, CSV (cĂłdigo seguro de verificaciĂłn) y detalle de errores.

Inputs: xml (required), response_type. Returns: object

es__query_sii_statusEs Query Sii StatusB

Consulta el estado de facturas en el SII mediante ConsultaFactInformadasEmitidas/Recibidas (SOAP).

ES-LC-2: reemplaza el REST GET no funcional por el envelope SOAP correcto. Filtra por ejercicio, periodo y, opcionalmente, por NIF del emisor y numero de factura.

Inputs: period (required), fiscal_year (required), nif_titular (required), nombre_titular (required), +3 more. Returns: object

es__query_verifactu_statusEs Query Verifactu StatusA

Consulta el EstadoRegistro de un registro VERI*FACTU ya enviado.

(ConsultaFactuSistemaFacturacion / ConsultaLR.xsd). Use esta tool tras un resultado 'deferred' de es__submit_verifactu_to_aeat, esperando retry_after_seconds, 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.

Inputs: nif (required), name (required), invoice_date (required), num_serie_factura. Returns: object

es__sign_facturae_xadesEs Sign Facturae XadesA

Aplica una firma digital XAdES-EPES (ETSI EN 319 132-1) a un documento Facturae XML.

Usa el certificado PKCS#12 indicado para firmar con SHA-256 + RSA. La polĂ­tica de firma por defecto es la de Facturae (Orden EHA/962/2007).

HUMAN-IN-THE-LOOP: llame sin confirmation_token para recibir un resumen de confirmación y un token; muéstrelo al usuario y vuelva a llamar con confirmation_token para aplicar la firma real.

Inputs: xml (required), cert_path, confirmation_token, signature_policy_id, +1 more. Returns: object

es__submit_sii_batchEs Submit Sii BatchA

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

Requiere AEAT_ENV, AEAT_CERTIFICATE_PATH y AEAT_CERTIFICATE_PASSWORD (MTLS).

HUMAN-IN-THE-LOOP: llame sin confirmation_token para recibir un resumen de confirmación y un token; muéstrelo al usuario y vuelva a llamar con confirmation_token para ejecutar el envío real.

Inputs: records (required), fiscal_year (required), record_type (required), confirmation_token. Returns: object

es__submit_to_faceEs Submit To FaceA

Envía un XML Facturae firmado con XAdES a FACe a través de la API REST B2B de FACe v2.

FACe = Punto General de Entrada de Facturas ElectrĂłnicas. AutenticaciĂłn JWS (RS256 + x5c) per FACe-manual-api-integradores.pdf s2.3: requiere FACE_ENV y AEAT_CERTIFICATE_PATH (+ AEAT_CERTIFICATE_PASSWORD).

HUMAN-IN-THE-LOOP: llame sin confirmation_token para recibir un resumen de confirmación y un token; muéstrelo al usuario y vuelva a llamar con confirmation_token para ejecutar el envío real.

Inputs: xml (required), management_body (required), accounting_office (required), administrative_unit (required), +1 more. Returns: object

es__submit_verifactu_to_aeatEs Submit Verifactu To AeatA

EnvĂ­a un registro VERI*FACTU firmado al endpoint en tiempo real de la AEAT mediante MTLS.

Usa el certificado FNMT-RCM. Requiere AEAT_ENV, AEAT_CERTIFICATE_PATH y AEAT_CERTIFICATE_PASSWORD. Si la respuesta trae parsed_response.status == 'deferred' (TiempoEsperaEnvio), espere retry_after_seconds y llame a es__query_verifactu_status para confirmar el EstadoRegistro final antes de encadenar el siguiente registro.

HUMAN-IN-THE-LOOP: llame sin confirmation_token para recibir un resumen de confirmación y un token; muéstrelo al usuario y vuelva a llamar con confirmation_token para ejecutar el envío real.

Inputs: nif (required), xml (required), confirmation_token. Returns: object

es__validate_facturae_schemaEs Validate Facturae SchemaA

Valida un XML Facturae contra el XSD oficial 3.2.2.

Realiza validación estructural y, si el XSD está disponible en resources/facturae/, también validación de esquema completa.

Inputs: xml (required), schema_version. Returns: object

es__validate_verifactu_recordEs Validate Verifactu RecordA

Valida un registro VERI*FACTU XML.

Realiza validación estructural y, si el XSD v1.0 (HAC/1177/2024) está disponible en resources/verifactu/, también validación de esquema.

Inputs: xml (required), schema_version. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 20 tools

    Disambiguation4/5

    Tools are mostly split cleanly by regime (VERI*FACTU, SII, FACe/Facturae) and lifecycle step, so an agent can usually pick the right one. However, generate_b2b_einvoice_es and generate_facturae_xml both generate invoices, while check_b2b_mandate_applicability, detect_regional_regime, and get_compliance_status all answer overlapping regime/compliance questions.

    Naming Consistency5/5

    All 20 tools use the es__ prefix plus a consistent snake_case verb_noun pattern (generate_, validate_, build_, submit_, query_, get_, cancel_, check_, detect_, parse_). The verbs vary appropriately by action while the structure remains predictable.

    Tool Count4/5

    Twenty tools is on the heavy side, but the domain spans three distinct Spanish e-invoicing regimes plus shared validation, signing, and compliance helpers, so each tool has a plausible role. Slightly over the ideal range but not bloated.

    Completeness4/5

    The surface covers generation, validation, submission, status query, and cancellation across VERI*FACTU and SII, plus Facturae generation, signing, FACe submission, and status checks. Minor gaps remain around FACe invoice cancellation/rejection workflows and richer querying of previously submitted SII/FACe invoices.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for DACH e-invoicing. Create XRechnung (UBL) and ZUGFeRD 2.3 (Factur-X CII) invoices, validate against EN 16931 rules, extract data from XML, and convert between UBL, CII and JSON formats.
      6
      50 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for French Electronic Invoicing (NF XP Z12-013). Provide tools to validate, generate, and explore API specifications for PDP/OD interoperability.
      34
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Italian Electronic Invoicing (FatturaPA / SDI). Provide tools to validate, generate, and explore API specifications for Sistema di Interscambio (SDI) interoperability.
      43
      93 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Belgian Electronic Invoicing (Peppol BIS 3.0 / PINT-BE / Mercurius). Provides tools to validate, generate, and transform UBL 2.1 e-invoices, and look up BCE/KBO enterprise data and Peppol participants.
      50
      297 PyPI
      Apache 2.0