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 分