Verifactu Mcp

io.github.KmOnBeIbI31Published by GitHub account KmOnBeIbI31v0.1.1Updated Oct 24, 2026

MCP server para VeriFactu (AEAT). Facturación electrónica española desde Claude Code.

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

MCP server that lets an assistant generate, send, cancel and check Spanish VeriFactu (AEAT) electronic invoice records from natural language.

What you can do
  • Generate and hash invoice records: build valid VeriFactu XML with a chained SHA-256 hash, or compute the hash of any record without sending it.
  • Send and cancel records: submit alta or anulación records to the AEAT through the verifactuapi.es API.
  • Check and list records: query the status of a record and list sent records with optional issuer and pagination filters.
  • Inspect local state: return the last hash stored locally for an issuer from a local SQLite audit log.
When to use it
Useful for Spanish businesses or developers that must issue VeriFactu-compliant electronic invoices and want to drive the AEAT workflow conversationally from Claude Code or Cursor instead of reading the AEAT technical documentation. Test against the sandbox first.
Requirements
Runs as a local Python process installed from PyPI (pip install -e . or python -m verifactu_mcp.server). Needs the VERIFACTU_API_TOKEN environment variable to send records, plus network access to the verifactuapi.es API. Optional variables: VERIFACTU_API_BASE (defaults to production) and VERIFACTU_STATE_DB (defaults to ~/.verifactu-mcp/state.db).
Before you install
Sending and cancelling records are real fiscal submissions to the AEAT; the default API base is production, so point VERIFACTU_API_BASE at the sandbox while testing. The README warns not to run the smoke test against production because it issues a real sandbox record. The API token is passed in the environment, and a local SQLite file keeps an audit log of hashes. Locally computed hashes are heuristic estimates, not the canonical AEAT fingerprint.

Installation

In SourceWeft

  1. Open Verifactu Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

verifactu-mcp

Servidor MCP para integrar VeriFactu (AEAT) con Claude Code y Cursor.

Permite generar, encadenar y enviar registros de facturación electrónica desde lenguaje natural, sin necesidad de leer la documentación técnica de la AEAT.

Herramientas disponibles

HerramientaDescripción
generate_invoice_xmlGenera XML válido con hash SHA-256 encadenado (sin enviar)
send_invoiceEnvía registro de alta a la AEAT via API y persiste la huella
cancel_invoiceEnvía registro de anulación
check_invoice_statusConsulta el estado de un registro
list_invoicesLista los registros enviados (filtros opcionales por emisor y paginación)
get_last_hashDevuelve la última huella registrada localmente para un emisor
calculate_hashCalcula el hash SHA-256 de cualquier registro

El encadenamiento real lo gestiona la API verifactuapi.es internamente (vía previous_id). El servidor MCP persiste la huella canónica que devuelve la API en SQLite local (~/.verifactu-mcp/state.db) como audit log, no como mecanismo de encadenamiento operativo. La herramienta get_last_hash consulta ese log.

calculate_hash y la huella huella_local_estimada de send_invoice son estimaciones heurísticas para inspección — la huella canónica AEAT incluye el timestamp server-side y solo el servidor puede generarla.

Smoke test contra sandbox

bash
$env:VERIFACTU_API_TOKEN = "<tu_token_sandbox>"python smoke_test.py <id_emisor> [nif_receptor]

Ejecuta list_invoices + send_invoice (¡emite registro real en sandbox!) + check_invoice_status + get_last_hash. NO ejecutar contra producción.

Instalación

bash
# 1. Clona el repositoriogit clone https://github.com/tuusuario/verifactu-mcpcd verifactu-mcp
# 2. Instala las dependenciaspip install -e .

Configuración en Claude Code

Tras pip install -e ., el script verifactu-mcp queda disponible globalmente. Añade esto a tu ~/.claude.json (o claude_desktop_config.json):

json
{  "mcpServers": {    "verifactu": {      "command": "verifactu-mcp",      "env": {        "VERIFACTU_API_TOKEN": "tu_token_aqui"      }    }  }}

Alternativa sin script instalado (vía python -m):

json
{  "mcpServers": {    "verifactu": {      "command": "python",      "args": ["-m", "verifactu_mcp.server"],      "cwd": "/ruta/a/verifactu-mcp",      "env": {        "VERIFACTU_API_TOKEN": "tu_token_aqui"      }    }  }}

Uso desde Claude Code

# Generar un XML sin enviar (ideal para pruebas)"Genera un registro VeriFactu para una factura de 100€ + 21% IVA, emisor B12345678, serie 2025/001, fecha 15-05-2025, descripción: Servicios de desarrollo web"
# Enviar a la AEAT — la huella anterior se resuelve automáticamente"Envía a la AEAT la factura 2025/001 del emisor B12345678, base 100€, IVA 21%, fecha hoy"
# Consultar estado"¿Cuál es el estado del registro con ID 42?"
# Anular una factura"Anula la factura 2025/001 del emisor B12345678"
# Listar las facturas enviadas"Lista las últimas 50 facturas enviadas para el emisor B12345678"
# Inspeccionar el último hash del emisor"¿Cuál es la última huella encadenada para B12345678?"

Variables de entorno

VariableDescripciónRequerida
VERIFACTU_API_TOKENToken de acceso a verifactuapi.esSí (para enviar)
VERIFACTU_API_BASEURL base de la API (por defecto producción)No
VERIFACTU_STATE_DBRuta a la DB SQLite de estado (por defecto ~/.verifactu-mcp/state.db)No

Entornos AEAT

EntornoURL
Sandboxhttps://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP
Producciónhttps://www1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP

Para certificados de prueba (sandbox): [email protected]

Licencia

MIT

Source: README.md at commit 9878e30

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts