contadeo-mcp
contadeo-mcp
Servidor MCP de Contadeo: conecta tu asistente de IA (Claude Desktop, Claude Code, Cursor…) a la facturación electrónica del SRI (Ecuador).
— "Emite una factura de 2 horas de consultoría a $75 para Juan Pérez, cédula 0923266183, pago por transferencia, y mándale el PDF a su correo"
El asistente busca (o crea) al cliente, el servidor calcula el IVA y cuadra los totales con las reglas oficiales del SRI, te muestra el resumen, y tras tu confirmación emite, espera la autorización del SRI y te entrega el RIDE.
Por qué es seguro
La matemática tributaria no la hace el modelo de IA — la hace este servidor, con las mismas reglas que valida Contadeo:
- Cálculo y cuadre de totales con aritmética decimal exacta (redondeo half-up a 2 decimales, agrupación de IVA por tarifa).
- Validación del dígito verificador de cédulas y RUC (los 3 tipos) antes de enviar nada — espejo verificado contra el núcleo fiscal de Contadeo (fuzz de 100 000 valores, 0 diferencias).
- Regla de consumidor final (identificación fija, máximo $50 — error SRI 69).
- Catálogos oficiales embebidos: tarifas de IVA (Tabla 18), formas de pago (Tabla 24), tipos de identificación (Tabla 7).
- El flujo exige confirmación humana:
preparar_facturasolo calcula y devuelve un resumen;emitir_facturare-valida el cuadre y rechaza payloads hechos a mano. - Ambiente siempre visible (Pruebas/Producción): el objeto
ambienteviaja en las respuestas y elresumenque confirmas encabeza con un banner ( Producción = documento tributario real). Nunca se describe "de memoria". confirmToken:preparar_*firma el resumen yemitir_*lo verifica — ata la emisión al resumen exacto que confirmaste y bloquea payloads modificados o resúmenes rancios (se activa conMCP_CONFIRM_SECRET).- Auditoría: cada emisión queda registrada (tenant, tool, latencia, sin datos personales) para depuración y cumplimiento.
- Reverso legal: para dejar sin efecto una factura se emite una nota de
crédito (
preparar_nota_credito/emitir_nota_credito) — la vía del SRI cuando ya no aplica la anulación (fuera del plazo del día 7, o consumidor final). La anulación interna (estadoANULADO) sigue haciéndose desde el panel; su trámite formal ante el SRI es en SRI en línea.
Requisitos
- Cuenta en contadeo.com (gratis: 10 comprobantes/mes)
con emisor y certificado
.p12configurados - Para el modo stdio: Node.js 18+ y una API key (panel →
Configuración → API → Crear; rol
emisorbasta)
Conexión recomendada: servidor remoto con OAuth
Sin API keys: el cliente abre el login de Contadeo, autorizas con un clic y listo (OAuth 2.1 con PKCE y registro dinámico de clientes).
# Claude Code
claude mcp add --transport http contadeo https://contadeo.com/api/mcp
# dentro de la sesión: /mcp → authenticate (abre el navegador)En claude.ai: Settings → Connectors → Add custom connector →
https://contadeo.com/api/mcp.
Para clientes que solo hablan stdio pero soportan OAuth vía proxy:
claude mcp add contadeo -- npx -y mcp-remote https://contadeo.com/api/mcpRevocar el acceso: cambia tu contraseña en Contadeo (invalida los tokens de todos los clientes conectados).
Método alternativo: stdio + API key
Útil para automatizaciones machine-to-machine o clientes sin MCP remoto.
La API key se crea en el panel (Configuración → API; el rol emisor
basta).
Claude Desktop / Cursor (claude_desktop_config.json)
{
"mcpServers": {
"contadeo": {
"command": "npx",
"args": ["-y", "contadeo-mcp"],
"env": { "CONTADEO_API_KEY": "cdo_tu_api_key" }
}
}
}Claude Code
claude mcp add contadeo -e CONTADEO_API_KEY=cdo_tu_api_key -- npx -y contadeo-mcpVariables de entorno (solo stdio)
| Variable | Requerida | Default |
|---|---|---|
CONTADEO_API_KEY |
— | |
CONTADEO_API_URL |
— | https://contadeo.com/api |
Tu primera factura (tutorial)
Recomendado: deja tu cuenta en ambiente de Pruebas (Configuración → Empresa) hasta dominar el flujo — los comprobantes de Pruebas no tienen validez tributaria.
Una conversación real se ve así:
Tú: Factúrale a María García, cédula 1714616123, 3 cajas de té a $4.50 cada una, pago en efectivo. Su correo es maria@correo.com
Asistente: (usa contexto_emision, crear_cliente y preparar_factura) Te muestro el resumen antes de emitir:
Factura para: MARIA GARCIA (Cédula 1714616123) Detalle: • 3 × Caja de té @ $4.50 = $13.50 [IVA 15% (tarifa general vigente)] Subtotal (sin impuestos): $13.50 IVA: $2.03 TOTAL: $15.53 Forma de pago: Sin utilización del sistema financiero (efectivo) RIDE se enviará a: maria@correo.com¿Confirmas la emisión?
Tú: Sí
Asistente: (emitir_factura → esperar_autorizacion) AUTORIZADA por el SRI en 8 segundos. Clave de acceso 2306…947. Aquí tienes el PDF: [descargar RIDE]. María también lo recibirá en su correo.
En clientes MCP que soportan prompts, el comando facturar arranca
este flujo guiado automáticamente.
Tools
| Categoría | Tool | Qué hace |
|---|---|---|
| Cuenta | consultar_cuenta |
Plan, consumo del mes y ambiente (Pruebas/Producción) |
| Contexto | contexto_emision |
Emisores, establecimientos, puntos y certificados (los IDs para emitir) |
| Catálogo | buscar_clientes / buscar_productos |
Búsqueda por texto |
| Catálogo | crear_cliente / crear_producto |
Altas (valida cédula/RUC y tarifas antes de enviar) |
| Catálogo | consultar_ruc |
Autocompleta al comprador por RUC/cédula (directorio + catastro SRI); alerta de contribuyente fantasma/inactivo |
| Emisión | preparar_factura |
Calcula y cuadra todo; devuelve resumen + payload (con idempotencyKey). fechaEmision opcional: default hoy, hasta 5 días atrás. No emite |
| Emisión | emitir_factura |
Emite tras confirmación; re-valida el cuadre localmente |
| Emisión | preparar_lote |
Hasta 25 facturas de una vez: datos comunes al lote + override por factura; devuelve resumenAgregado (tabla por factura + totales). No emite |
| Emisión | emitir_lote |
Emite el lote en secuencia tras UNA confirmación; pre-vuelo todo-o-nada y estado por factura (ENCOLADA/FALLO/NO_INTENTADA) |
| Reverso | preparar_nota_credito |
Nota de crédito (04) que revierte una factura: reverso TOTAL desde comprobanteId + motivo, o explícito/parcial con items. Calcula y cuadra; no emite |
| Reverso | emitir_nota_credito |
Emite la nota de crédito tras confirmación; re-valida cuadre y confirmToken |
| Emisión | esperar_autorizacion |
Polling hasta AUTORIZADO/RECHAZADO (el SRI tarda 5–30 s); acepta id o ids (hasta 25, para lotes). Los AUTORIZADO incluyen los links de descarga del RIDE y XML |
| Consulta | listar_comprobantes / consultar_comprobante |
Estados y detalle; con eventos: true incluye el timeline paso a paso de la emisión |
| Descarga | descargar_ride / descargar_xml |
URLs temporales (1 h) del PDF y XML |
| Acción | anular_comprobante / reenviar_comprobante |
Anula una factura autorizada (registro interno; si no aplica, orienta a nota de crédito) o reenvía el RIDE/XML por email |
| Reportes | reporte_ventas |
Agregados del período |
| Multi-cuenta | listar_mis_cuentas / consultar_cartera |
Contadores: todas tus empresas y su cartera (semáforo RIMPE + vencimientos) de un vistazo. Solo OAuth |
| Referencia | consultar_reglas_sri |
Tablas oficiales: tarifas IVA, formas de pago, identificaciones, reglas |
| Asesor | consultar_calendario_tributario |
Próximos vencimientos según el 9.º dígito del RUC y el régimen |
| Asesor | consultar_semaforo_rimpe |
Proyección de ingresos vs límites RIMPE: VERDE/AMARILLO/ROJO |
| Asesor | consultar_obligaciones |
Checklist de obligaciones del perfil (declaraciones, anexos, contabilidad) |
| Asesor | consultar_f104 |
Borrador del F104 de IVA explicado: cifras + resumen en español llano, desglose por casillero (429, 564, 601, 605, 609, 902/615), alertas proactivas y proyección del arrastre — no es la declaración oficial |
| Asesor | explicar_f104 |
Narra la declaración casillero por casillero para quien nunca ha declarado; también explica cifras pegadas de una declaración ya presentada |
| Asesor | simular_f104 |
"¿Si facturo $500 más, cuánto más pago?": escenarios de ventas/compras/retenciones/ventas a crédito sobre el borrador, con la tarifa vigente del servidor |
| Asesor | validar_f104 |
Chequeo previo a declarar: cruza el borrador contra los libros, detecta compras sin autorización, notas de crédito por compensar y diferencias con lo que piensas declarar |
| Asesor | consultar_libro_ventas / consultar_libro_compras |
Libros de ventas y de compras del período (líneas + totales, insumo de declaración y ATS) |
| Asesor | consultar_cumplimiento_despacho |
Vista cross-empresa del despacho: alertas urgentes, semáforos RIMPE, bandeja de vencimientos y resumen. Parámetro vista filtra los bloques. Solo OAuth. |
Los tools del Asesor son informativos: el servidor calcula con sus catálogos legislativos vigentes y toda respuesta incluye un
disclaimer(«no constituye asesoría tributaria») que el asistente siempre muestra. 34 tools en total. El catálogo se filtra portenants.perfil: el negocio ve 31 y el contador ve las 34 — suma las 3 de despacho multiempresa (listar_mis_cuentas,consultar_cartera,consultar_cumplimiento_despacho), que requieren sesión OAuth.
Campos de respuesta (v0.7.0):
preparar_*incluye el objetoambiente,preparadoEny unconfirmTokenen cada payload (reenvíalo tal cual, junto alidempotencyKey);emitir_*devuelve elambientelegible yencoladoEn(y en el loteestadoComprobante);esperar_autorizacionyconsultar_comprobantetraen elambientelegible, y coneventos:trueel timeline incluye firmado → enviado → autorizado → notificado. El detalle interno de arquitectura vive endocs/MCP.md.
Lotes: varias facturas de una vez
Para emitir hasta 25 facturas en una sola pasada (p. ej. la facturación mensual a toda la cartera):
preparar_lote— construye el lote con la matemática hecha por el servidor: comprador, forma de pago yfechaEmisioncomunes al lote, con override por factura. Devuelve elresumenAgregado(tabla por factura + totales del lote).- UNA confirmación — el asistente muestra la tabla completa y pide una única confirmación explícita del lote entero antes de emitir.
emitir_lote— emite en secuencia con pre-vuelo todo-o-nada (si un payload no cuadra, no se emite ninguna); si una factura falla continúa con las demás, salvo 401/402/429 que corta el lote.esperar_autorizacionconids— sigue todos los comprobantes hasta el estado terminal (timeout sugerido: 90 s).
Reintentos seguros: cada payload lleva su idempotencyKey (lo genera
preparar_lote); reintentar la emisión con la misma clave devuelve el
comprobante original — no quema secuenciales ni duplica facturas.
Reglas del SRI que el servidor aplica por ti
| Regla | Detalle |
|---|---|
| Tarifas de IVA (Tabla 18) | '4' = 15% (general vigente) · '0' = 0% · '5' = 5% · '7' = exento · '6' = no objeto |
| Formas de pago (Tabla 24) | '01' efectivo · '20' transferencia · '19' t. crédito · '16' t. débito · más en consultar_reglas_sri |
| Identificación (Tabla 7) | '04' RUC · '05' cédula · '06' pasaporte · '07' consumidor final — con dígito verificador validado |
| Consumidor final | Identificación fija 9999999999999, importe máximo $50 |
| Cuadre | línea = cantidad×precio−descuento; IVA = base×tarifa/100; total = subtotal+IVA+propina — redondeo half-up a 2 decimales |
| Fecha de emisión | Default: hoy (calendario de Ecuador). fechaEmision opcional acepta hasta 5 días atrás; nunca futura (la API la rechaza — error 65 SRI) |
Skill para Claude (opcional, recomendado)
La carpeta skill/facturacion-contadeo/
contiene un Agent Skill que le enseña a Claude el flujo completo, las
reglas de oro (nunca emitir sin confirmación, nunca calcular de cabeza,
verificar el ambiente) y el manejo de errores del SRI. Instalación en Claude
Code:
mkdir -p ~/.claude/skills && cp -r node_modules/contadeo-mcp/skill/facturacion-contadeo ~/.claude/skills/(o copia la carpeta a .claude/skills/ de tu proyecto).
Troubleshooting
| Síntoma | Causa probable | Solución |
|---|---|---|
401 API key inválida o revocada |
Key mal copiada o revocada | Genera otra en Configuración → API |
402 Cupo mensual agotado |
Límite del plan | contadeo.com/precios |
RECHAZADO con error 62 |
Identificación inválida | El flujo normal lo previene; revisa el número con el comprador |
RECHAZADO con error 52 |
Totales descuadrados | Usa siempre preparar_factura; no edites el payload |
Queda en ENVIADO/CONTINGENCIA |
SRI lento o caído | Reintentos automáticos; consulta en unos minutos |
| La factura salió "de verdad" sin querer | Cuenta en Producción | Cambia a Pruebas en Configuración → Empresa para experimentar |
Desarrollo
# desde la raíz del monorepo (el paquete vive en el workspace)
pnpm install
pnpm --filter contadeo-mcp test # vitest: identificación + cálculo/cuadre
pnpm --filter contadeo-mcp build # tsc → dist/
CONTADEO_API_KEY=cdo_... node mcp/dist/index.js # corre por stdioEl paquete exporta crearServidorContadeo({ apiUrl, token, confirmSecret?, onAuditoria? }): la misma factoría que usa el backend de Contadeo para montar
el servidor remoto en https://contadeo.com/api/mcp. Arquitectura interna
(protocolo, garantías, modelo de datos): docs/MCP.md; transporte/OAuth y
despliegue: docs/MCP-REMOTO.md.
Documentación completa de la API REST: https://contadeo.com/desarrolladores