sunat-datos-abiertos-mcp

Servidor MCP (Model Context Protocol) + CLI para consultar los datasets de SUNAT publicados en la Plataforma Nacional de Datos Abiertos del Perú: padrón RUC con clasificación CIIU, padrón de emisores de comprobantes electrónicos, agentes de retención/percepción de IGV, etc.

La idea central: los archivos son enormes (el padrón RUC son ~230 MB comprimidos y ~3 GB de CSV con 12.5 millones de filas) y descargarlos para responder una pregunta no tiene sentido. Este servidor los lee en streaming y filtra, agrupa y perfila sobre la marcha, sin escribir nada en disco.

Requisitos

• Node.js 18+ (probado en Node 24)

Related MCP server: datagovma-mcp

Instalación

npm install
npm run build

Tools disponibles (MCP)

Catálogo

Datos

Flujo típico: sunat_buscar_recursos → sunat_perfilar_recurso → sunat_buscar_en_recurso o sunat_contar_por_columna.

Particularidades del portal (verificadas contra la API real)

Este portal es CKAN, pero con varias trampas. Todas están resueltas en el código:

• package_search y organization_list devuelven 404. Por eso se navega el grupo de SUNAT con group_package_show y la búsqueda por palabras clave se hace en cliente.

• Ante un error el portal responde HTML, no JSON. Se valida el content-type antes de parsear, así el fallo dice qué pasó en vez de reventar con un error de sintaxis JSON.

• package_show y group_package_show envuelven el resultado en un array de un solo elemento, a diferencia de package_list/resource_show. Se desenvuelve solo si hace falta.

• El WAF responde 418 a ciertos User-Agent (curl/*, o cualquiera con una URL entre paréntesis). El User-Agent se mantiene como un token simple producto/versión a propósito.

• El campo format miente: los padrones RUC se declaran csv pero se sirven como .zip. El tipo se decide por los bytes reales (firma PK), no por la metadata; cada recurso reporta además un formato_real.

• El delimitador varía entre archivos: PadronRUC_202209.csv usa | y PadronRUC_202412.csv usa ,. Se detecta por archivo, junto con ; y tabulador.

• El encoding varía: el padrón RUC es latin1 y el de agentes de retención es utf-8. Se detecta con los primeros bytes, así que HUÁNUCO y ENSEÑANZA no salen mojibake.

Uso con Claude Desktop / Claude Code

{
  "mcpServers": {
    "sunat-datos-abiertos": {
      "command": "node",
      "args": ["C:\\source\\mcp-sunat\\build\\index.js"]
    }
  }
}

Uso como CLI

npm run build
npm link        # instala el comando `sunat` globalmente

sunat list                                   # datasets de SUNAT
sunat search padron ruc 2024-12              # busca recursos por palabras clave
sunat show <dataset>                         # detalle y recursos de un dataset
sunat latest <dataset>                       # el recurso más reciente
sunat resource <resource_id>                 # metadata y URL de un recurso

sunat schema <resource_id>                   # columnas reales, tipos, ejemplos
sunat preview <resource_id> -n 50            # primeras filas parseadas
sunat find <resource_id> -w RUC=20100070970  # busca filas sin descargar el archivo
sunat count <resource_id> Departamento -w Estado=ACTIVO   # group by en streaming

sunat download <resource_id> -o ./padron.zip # descarga completa
sunat cache status | clear | path            # caché local

Filtros de find/count (-w, repetible):

Las comparaciones ignoran tildes y mayúsculas (huanuco encuentra HUÁNUCO).

Flags globales: --json (salida cruda para pipes) y --no-color.

Ejemplo real

$ sunat find a6892afd-f622-4564-8acd-44644912fcb4 -w RUC=20100070970 \
      -c RUC,Estado,Condicion,Tipo,Departamento
┌─────────────┬────────┬───────────┬──────────────────┬──────────────┐
│ RUC         │ Estado │ Condicion │ Tipo             │ Departamento │
├─────────────┼────────┼───────────┼──────────────────┼──────────────┤
│ 20100070970 │ ACTIVO │ HABIDO    │ SOCIEDAD ANONIMA │ LIMA         │
└─────────────┴────────┴───────────┴──────────────────┴──────────────┘
1 coincidencia(s) | 12,515,483 filas escaneadas | 3.1 GB leidos | escaneo completo: si

12.5 millones de filas recorridas, cero bytes escritos en disco. El tiempo lo pone la red (~3 min con esa conexión), no el parseo.

Configuración por entorno

Solo se cachea la metadata del catálogo (cambia poco). El contenido de los archivos nunca se cachea, y un resultado que no se pudo interpretar tampoco: así un error puntual del portal no envenena la caché.

Límites conocidos

• Un campo entrecomillado que contenga saltos de línea no está soportado (los archivos de este portal no los usan; soportarlo obligaría a bufferear filas completas).

• sunat_contar_por_columna rechaza columnas con más de 50 000 valores distintos: agrupar por RUC no tiene sentido, para eso está sunat_buscar_en_recurso.

• escaneo_completo: false significa que el conteo es parcial (se cortó por límite de filas, bytes o coincidencias). Siempre revisa ese campo antes de afirmar un total.

Desarrollo

npm run build   # compila TypeScript a build/
npm start       # corre el servidor MCP compilado
node build/cli.js list   # corre la CLI sin npm link

Licencia

MIT. Ver LICENSE.