English Français العربية

io.github.KmOnBeIbI31/verifactu-mcp

السجل الرسمي أدوات المطورين

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

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package verifactu-mcp
Claude Code 
claude mcp add verifactu-mcp -- uvx verifactu-mcp==0.1.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "verifactu-mcp": {
            "command": "uvx",
            "args": [
                "verifactu-mcp==0.1.1"
            ]
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. verifactu-mcp
  2. Herramientas disponibles
  3. Instalación
  4. Configuración en Claude Code
  5. Uso desde Claude Code
  6. Variables de entorno
  7. Entornos AEAT
  8. Licencia

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

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

# 2. Instala las dependencias
pip 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):

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

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

{
  "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): catentidades@correo.aeat.es

Licencia

MIT

الأسئلة الشائعة

ما هو io.github.KmOnBeIbI31/verifactu-mcp؟

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

كيف أثبّت io.github.KmOnBeIbI31/verifactu-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add verifactu-mcp -- uvx verifactu-mcp==0.1.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.KmOnBeIbI31/verifactu-mcp إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.KmOnBeIbI31/verifactu-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.KmOnBeIbI31/verifactu-mcp؟

ينشره KmOnBeIbI31. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.