# recibo.ec MCP

> Servidor MCP (Model Context Protocol) para consultar los comprobantes electrónicos del SRI de un usuario de recibo.ec: facturas, notas de crédito, notas de débito, liquidaciones de compra y retenciones. Acceso de SOLO LECTURA autorizado por el propio usuario.

## Conexión

- Endpoint MCP: https://mcp.recibo.ec/mcp (Streamable HTTP; no hay endpoint SSE legado)
- Autenticación: OAuth 2.1 con registro dinámico de clientes (RFC 7591, POST https://mcp.recibo.ec/register) y PKCE S256 obligatorio; no se necesitan client_id ni secret previos
- Alcance único: comprobantes:leer
- Metadatos: https://mcp.recibo.ec/.well-known/oauth-protected-resource y https://mcp.recibo.ec/.well-known/oauth-authorization-server
- El usuario inicia sesión en la pantalla de autorización con correo + código, Google o su clave del SRI; con correo/Google la cuenta debe tener una cédula o RUC verificado en https://recibo.ec/portal/
- El usuario revoca el acceso por aplicación en https://recibo.ec/portal/

## Configuración por cliente

- Claude (web/escritorio/móvil): Ajustes > Conectores > Añadir conector personalizado > pegar https://mcp.recibo.ec/mcp
- Claude Code: claude mcp add --transport http recibo https://mcp.recibo.ec/mcp
- ChatGPT (Plus/Pro/Team/Enterprise/Edu): activar Modo de desarrollador en Ajustes > Aplicaciones y conectores > Ajustes avanzados; crear conector con la URL y autenticación OAuth
- Cursor y LM Studio (mcp.json): {"mcpServers":{"recibo.ec":{"url":"https://mcp.recibo.ec/mcp"}}}
- VS Code (mcp.json, clave raíz "servers"): {"servers":{"recibo.ec":{"type":"http","url":"https://mcp.recibo.ec/mcp"}}}
- Windsurf (~/.codeium/windsurf/mcp_config.json): {"mcpServers":{"recibo.ec":{"serverUrl":"https://mcp.recibo.ec/mcp"}}}
- Gemini CLI (~/.gemini/settings.json): {"mcpServers":{"recibo":{"httpUrl":"https://mcp.recibo.ec/mcp"}}} (OAuth se descubre solo)
- Codex CLI (~/.codex/config.toml): [mcp_servers.recibo] con url = "https://mcp.recibo.ec/mcp"; luego: codex mcp login recibo
- Clientes solo-stdio: puente mcp-remote, {"mcpServers":{"recibo.ec":{"command":"npx","args":["-y","mcp-remote","https://mcp.recibo.ec/mcp"]}}} (o pnpm dlx mcp-remote)

## Herramientas (9, todas de consulta)

- identidades_disponibles: cédulas/RUC verificados de la conexión; llamarla primero
- consultar_comprobantes(identificacion, tipo=facturas|notas-credito|notas-debito|liquidaciones-compra|retenciones, desde, hasta, contraparte, producto, monto_min, monto_max, perspectiva=compras|ventas, ambiente=produccion|pruebas, limit<=100, cursor): listado paginado; la clave del arreglo depende del tipo (facturas, notas_credito, retenciones...); cada fila trae numero_autorizacion
- resumen_compras(identificacion, tipo, desde, hasta, contraparte, producto, perspectiva, ambiente, dias_serie 0..2000): KPIs (total_facturas, monto_total, monto_total_sin_impuestos, ticket_promedio, percentiles), top_productos, top_emisores y serie diaria; con dias_serie=0 solo KPIs
- principales_proveedores(identificacion, tipo, desde, hasta, perspectiva, ambiente, limit<=50): ranking por monto
- resumen_productos(identificacion, desde, hasta, producto, group_by, perspectiva, ambiente): productos agrupados, solo facturas
- comprobantes_por_categoria(identificacion, desde, hasta, perspectiva, ambiente): filas por emisor con su categoría de gasto; agregar por categoria
- buscar_contraparte(identificacion, q, tipo_documento, perspectiva, ambiente): nombre a RUC/cédula; coincide contra razón social y nombre comercial (incluidos los nombres de fantasía de los locales), ignorando espacios, tildes y signos
- comprobante_por_clave(clave_acceso de 49 dígitos): documento completo línea por línea; NO requiere identificacion (la clave es la llave, como en el SRI)
- enlace_pdf(numero_autorizacion): URL del PDF imprimible (RIDE)

## Reglas para el agente

1. Llamar identidades_disponibles al inicio; si hay varias identidades, preguntar al usuario cuál usar y pasarla como "identificacion" en cada consulta (el servidor rechaza consultas ambiguas)
2. Fechas siempre absolutas AAAA-MM-DD (resolver "junio" o "el mes pasado" antes de llamar); desde/hasta son inclusivas
3. ambiente=produccion salvo pedido explícito; perspectiva=ventas solo si la identidad es un RUC
4. Paginar reenviando next_cursor como cursor mientras has_next sea true
5. El listado no trae el detalle interno: para productos, impuestos y formas de pago usar comprobante_por_clave con el numero_autorizacion de la fila
6. Los errores vuelven como texto con isError y el prefijo "No se pudo consultar:"; el detalle indica la corrección (identidad no verificada, varias identidades, formato)
7. Nunca pedir la clave del SRI ni códigos por chat: la autenticación ocurre solo en la pantalla de autorización de https://mcp.recibo.ec

## Enlaces

- Guía completa (HTML): https://mcp.recibo.ec/guia
- Crear cuenta y verificar identidad: https://recibo.ec y https://recibo.ec/portal/
- Especificación MCP: https://modelcontextprotocol.io