Verifactu Mcp

io.github.KmOnBeIbI31由 GitHub 账号 KmOnBeIbI31 发布v0.1.1更新于 Oct 24, 2026

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

已验证STDIO仅桌面金融商业与电商

概览

AI 生成的概览

该 MCP 服务器让助手用自然语言生成、发送、作废并查询西班牙 VeriFactu（AEAT）电子发票记录。

可以做什么
  • 生成与计算哈希：构建带 SHA-256 链式哈希的合规 VeriFactu XML，或计算任意记录的哈希而不发送。
  • 发送与作废记录：通过 verifactuapi.es 接口向 AEAT 提交 alta 或 anulación 记录。
  • 查询与列出记录：查询某条记录的状态，并按开票方和分页条件列出已发送记录。
  • 查看本地状态：从本地 SQLite 审计日志返回某开票方最后记录的哈希。
适用场景
适合需要开具符合 VeriFactu 要求的电子发票的西班牙企业或开发者，希望在 Claude Code 或 Cursor 中通过对话完成 AEAT 流程，而不必阅读 AEAT 技术文档。建议先在沙箱环境测试。
运行要求
以本地 Python 进程运行，从 PyPI 安装（pip install -e . 或 python -m verifactu_mcp.server）。发送记录需要环境变量 VERIFACTU_API_TOKEN，并需能访问 verifactuapi.es 接口。可选变量：VERIFACTU_API_BASE（默认生产环境）和 VERIFACTU_STATE_DB（默认 ~/.verifactu-mcp/state.db）。
安装前请注意
发送和作废记录是向 AEAT 提交的真实税务申报；接口默认指向生产环境，测试时应把 VERIFACTU_API_BASE 指向沙箱。README 提醒不要对生产环境运行冒烟测试，因为它会在沙箱中开出真实记录。API 令牌通过环境变量传入，本地 SQLite 文件会保存哈希审计日志。本地计算的哈希只是启发式估算，并非 AEAT 的规范指纹。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Verifactu Mcp，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 9878e30

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分