mcp-facturacion-electronica-es

# mcp-facturacion-electronica-es 🇪🇸

[English](README.md) | [Espanol](README.es.md)

<!-- mcp-name: io.github.cmendezs/mcp-facturacion-electronica-es -->

![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
[![PyPI version](https://img.shields.io/pypi/v/mcp-facturacion-electronica-es.svg)](https://pypi.org/project/mcp-facturacion-electronica-es/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-facturacion-electronica-es.svg)](https://pypi.org/project/mcp-facturacion-electronica-es/) [![mcp-facturacion-electronica-es MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-facturacion-electronica-es/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-facturacion-electronica-es)

---

## 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**](https://github.com/cmendezs/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)

```bash
pip install mcp-facturacion-electronica-es
```

Without prior installation, using `uvx`:

```bash
uvx mcp-facturacion-electronica-es
```

### From source

```bash
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:

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

## 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`

```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`

```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` |

```json
{
  "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"`) |

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

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