verifactu-mcp

Name: verifactu-mcp
Author: KmOnBeIbI31

本地服务

github.com/KmOnBeIbI31金融数据023 周前更新

代码仓库

关于 verifactu-mcp

verifactu-mcp 将 Claude Code 和 Cursor 连接到西班牙 VeriFactu 电子发票服务。它可生成发票 XML、提交或撤销记录，并将 API 返回的规范指纹保存到本地 SQLite 审计日志。

主要功能

01生成带链式 SHA-256 哈希的发票 XML
02提交和撤销发票记录
03查询记录状态并列出提交记录
04在 SQLite 中保存规范指纹
05计算启发式 SHA-256 估值

适用场景

01生成发票记录但暂不提交
02向 AEAT 发送发票记录
03查看已提交记录及其状态

MCP 相关

它向 MCP 客户端提供 VeriFactu 发票生成、提交、撤销和查询工具，并使用 verifactuapi.es 与 AEAT API。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "kmonbeibi31-verifactu": {
      "command": "uvx",
      "args": [
        "verifactu-mcp"
      ]
    }
  }
}

启动命令uvx verifactu-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiverifactu-mcp0.1.1stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

verifactu-mcp

用于将 VeriFactu (AEAT) 与 Claude Code 和 Cursor 集成的 MCP 服务。

无需阅读 AEAT 的技术文档，即可通过自然语言生成、串联并发送电子发票记录。

可用工具

工具	描述
`generate_invoice_xml`	生成有效的 XML，并串联 SHA-256 哈希（不发送）
`send_invoice`	通过 API 向 AEAT 发送登记记录并保存哈希
`cancel_invoice`	发送注销记录
`check_invoice_status`	查询记录状态
`list_invoices`	列出已发送的记录（可选按开票方筛选并分页）
`get_last_hash`	返回本地为某个开票方记录的最新哈希
`calculate_hash`	计算任意记录的 SHA-256 哈希

实际的串联由 verifactuapi.es API 在内部处理（通过 previous_id）。MCP 服务会将 API 返回的规范哈希 保存到本地 SQLite （~/.verifactu-mcp/state.db）作为 审计日志，而不是将其用作实际串联机制。工具 get_last_hash 会查询该日志。

calculate_hash 和 send_invoice 返回的 huella_local_estimada 是用于检查的 启发式估算值——AEAT 规范哈希包含服务端时间戳，只有服务器才能生成。

对 sandbox 执行冒烟测试

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

执行 list_invoices + send_invoice（会在 sandbox 中发送真实记录！）+ check_invoice_status + get_last_hash。请勿对生产环境执行。

安装

# 1. Clona el repositorio
git clone https://github.com/tuusuario/verifactu-mcp
cd verifactu-mcp

# 2. Instala las dependencias
pip install -e .

在 Claude Code 中配置

运行 pip install -e . 后，脚本 verifactu-mcp 将全局可用。将以下内容添加到你的 ~/.claude.json（或 claude_desktop_config.json）中：

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

也可不安装脚本（通过 python -m）：

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

在 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?"

环境变量

变量	描述	必需
`VERIFACTU_API_TOKEN`	verifactuapi.es 的访问令牌	是（发送时）
`VERIFACTU_API_BASE`	API 基础 URL（默认为生产环境）	否
`VERIFACTU_STATE_DB`	状态 SQLite 数据库路径（默认为 `~/.verifactu-mcp/state.db`）	否

AEAT 环境

环境	URL
Sandbox	`https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP`
生产环境	`https://www1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP`

测试证书（sandbox）：[email protected]