@fiscalcloud/mcp — Servidor MCP de FiscalCloud

Servidor MCP para la API de timbrado CFDI 4.0 de FiscalCloud (integradores). Deja que tu agente de IA (Claude Desktop, Cursor, VS Code, etc.) timbre, valide, cancele y consulte comprobantes usando tu API key.

Sandbox por defecto. Timbrar CFDI mueve dinero y tiene efectos fiscales: el servidor usa el sandbox salvo que apuntes explícitamente a producción (y hayas certificado).

Requisitos

• Node.js ≥ 18.
• Una API key de integrador (genérala en tu portal → API keys; arranca en sandbox).

Uso rápido

FISCALCLOUD_API_KEY=tu_api_key_sandbox npx -y @fiscalcloud/mcp

Configuración en Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "fiscalcloud": {
      "command": "npx",
      "args": ["-y", "@fiscalcloud/mcp"],
      "env": {
        "FISCALCLOUD_API_KEY": "tu_api_key_de_sandbox",
        "FISCALCLOUD_API_BASE": "https://sandbox-api.fiscalcloud.mx/v1"
      }
    }
  }
}

Para producción (ya certificado): tu API key de producción y FISCALCLOUD_API_BASE=https://api.fiscalcloud.mx/v1.

Variables de entorno

| Variable | Obligatoria | Default | Descripción | |---|---|---|---| | FISCALCLOUD_API_KEY | Sí | — | API key Bearer de tu cuenta integradora. | | FISCALCLOUD_API_BASE | No | https://sandbox-api.fiscalcloud.mx/v1 | Base de la API (sandbox o producción). |

Herramientas

| Tool | Qué hace | |---|---| | saldo | Saldo de timbres disponibles. | | timbrar | Timbra un CFDI (modo relay o sellar). | | validar | Valida sin timbrar (solo sandbox). | | comprobantes_listar | Lista los comprobantes timbrados. | | comprobante_obtener | Consulta uno por UUID. | | comprobante_estatus_sat | Estatus del comprobante ante el SAT. | | cancelar | Cancela ante el SAT (motivo 01–04). | | buscar_en_docs | Trae la documentación completa (llms-full.txt). |

El cuerpo de timbrar/validar sigue el OpenAPI: https://integrador.fiscalcloud.mx/docs/api/openapi.yaml.

Seguridad

• Guarda la API key en variables de entorno; nunca en el código ni en prompts compartidos.
• El servidor solo reenvía tu API key a la API de FiscalCloud; no la registra ni la imprime.

Publicar (interno)

Este paquete vive en el monorepo (integrations/mcp-fiscalcloud/). Para publicarlo en npm como @fiscalcloud/mcp: npm publish --access public desde esta carpeta (requiere la org @fiscalcloud en npm). Mientras no esté publicado, se puede usar con npx -y /ruta/al/repo/integrations/mcp-fiscalcloud.