mcp-chilegob-dataset

English summary: MCP server that exposes Chile's open government data portal (datos.gob.cl) as tools for AI assistants. Search and read thousands of public datasets from Chilean government institutions — health, education, transport, environment, and more. No API key required.

Servidor MCP que expone el portal de datos abiertos del gobierno de Chile — datos.gob.cl — como herramientas para asistentes de inteligencia artificial.

Construido con Hono y el SDK de TypeScript del Model Context Protocol.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA (Claude, etc.) conectarse a herramientas y fuentes de datos externas de manera estructurada y segura. En lugar de copiar datos crudos en una conversación, el asistente llama a una herramienta y recibe resultados estructurados.

¿Qué es datos.gob.cl?

datos.gob.cl es el portal oficial de datos abiertos del gobierno de Chile, impulsado por CKAN. Contiene miles de datasets públicos de instituciones gubernamentales — salud, educación, transporte, medio ambiente, y más. Todos los datos son de acceso público, sin registro ni autenticación.

Instalación y uso rápido

Con Claude Code (un comando)

claude mcp add chilegob -- npx -y mcp-chilegob-dataset

Eso es todo. El servidor queda registrado globalmente en tu Claude Code. Reinicia la sesión y ya puedes usarlo.

Con Claude Desktop

Paso 1 — Abre la configuración de Claude Desktop.

En Mac: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%\Claude\claude_desktop_config.json

Paso 2 — Agrega la configuración según tu sistema operativo:

Mac / Linux:

{
  "mcpServers": {
    "chilegob": {
      "command": "npx",
      "args": ["-y", "mcp-chilegob-dataset"]
    }
  }
}

Windows:

Primero instala el paquete globalmente:

npm install -g mcp-chilegob-dataset

Luego agrega la configuración reemplazando TU_USUARIO con tu nombre de usuario de Windows:

{
  "mcpServers": {
    "chilegob": {
      "command": "node",
      "args": [
        "C:\\Users\\TU_USUARIO\\AppData\\Roaming\\npm\\node_modules\\mcp-chilegob-dataset\\dist\\stdio.js"
      ]
    }
  }
}

Paso 3 — Reinicia Claude Desktop.

Eso es todo. Puedes pedirle a Claude cosas como:

"Busca datasets sobre educación en datos.gob.cl" "Muestra los datos del dataset de matrícula universitaria" "¿Qué datasets de salud hay disponibles?"

Herramientas disponibles

Este servidor expone tres herramientas que el asistente puede usar automáticamente.

search_datasets

Busca datasets en datos.gob.cl por palabra clave. Devuelve una lista resumida.

Parámetros:

| Nombre | Tipo | Requerido | Por defecto | Descripción | |--------|------|-----------|-------------|-------------| | query | string | ✅ | — | Texto de búsqueda (en español o inglés) | | limit | number | ❌ | 10 | Máximo de resultados (1–100) |

Ejemplo de respuesta:

[
  {
    "id": "matricula-en-educacion-superior",
    "title": "Matrícula en Educación Superior",
    "description": "Bases de datos de matrícula en el sistema de educación superior...",
    "organization": "Subsecretaría de Educación",
    "resource_count": 1
  }
]

get_dataset

Obtiene los metadatos completos de un dataset: descripción, recursos, etiquetas y licencia.

Parámetros:

| Nombre | Tipo | Requerido | Descripción | |--------|------|-----------|-------------| | id | string | ✅ | Slug o UUID del dataset (obtenido de search_datasets) |

Ejemplo de respuesta:

{
  "id": "matricula-en-educacion-superior",
  "title": "Matrícula en Educación Superior",
  "organization": "Subsecretaría de Educación",
  "license": "Creative Commons Non-Commercial (Any)",
  "tags": ["educación", "educación superior", "matriculas"],
  "resources": [
    {
      "id": "37377aff-6df8-4424-9228-2f44f3e67fcd",
      "name": "Base de datos de matrícula",
      "format": "CSV",
      "url": "https://datosabiertos.mineduc.cl/...",
      "datastore_available": true
    }
  ]
}

Verifica el campo datastore_available antes de usar get_resource_data. Los recursos sin datastore deben descargarse desde su url.

get_resource_data

Lee filas tabulares de un recurso CKAN. Intenta primero el datastore y, si no está disponible, descarga y parsea el archivo directamente. Soporta paginación.

Estrategia de obtención de datos (automática):

1. Datastore CKAN — acceso estructurado y rápido; disponible solo en algunos recursos.
2. Descarga directa — si el datastore no está habilitado, la herramienta descarga el archivo y lo parsea en memoria:
   • CSV / TSV — parseado nativo, devuelve filas y columnas.
   • JSON — parseado nativo si el contenido es un array de objetos.
   • XLS, PDF y otros formatos binarios — no se parsean; se devuelve la URL directa para que el usuario los descargue.

Parámetros:

| Nombre | Tipo | Requerido | Por defecto | Descripción | |--------|------|-----------|-------------|-------------| | resource_id | string | ✅ | — | UUID del recurso (obtenido de get_dataset) | | limit | number | ❌ | 50 | Filas a devolver (1–500) | | offset | number | ❌ | 0 | Desplazamiento para paginación |

Ejemplo de respuesta (datastore):

{
  "source": "datastore",
  "total": 42,
  "returned": 3,
  "offset": 0,
  "fields": [
    { "id": "Region", "type": "text" },
    { "id": "Provincia", "type": "text" },
    { "id": "Comuna", "type": "text" }
  ],
  "records": [
    { "Region": "COQUIMBO", "Provincia": "ELQUI", "Comuna": "LA SERENA" }
  ]
}

Ejemplo de respuesta (archivo CSV descargado):

{
  "source": "file",
  "format": "CSV",
  "url": "https://datosabiertos.mineduc.cl/...",
  "total": 1500,
  "returned": 50,
  "offset": 0,
  "fields": [
    { "id": "Region", "type": "text" }
  ],
  "records": [
    { "Region": "METROPOLITANA" }
  ]
}

Ejemplo de respuesta (formato no parseable):

{
  "source": "file",
  "parseable": false,
  "format": "XLS",
  "url": "https://datosabiertos.mineduc.cl/archivo.xls",
  "message": "This resource is a XLS file and cannot be parsed automatically. Download it directly from the URL provided."
}

Para desarrolladores

Requisitos

• Node.js 20 o superior
• npm

Instalación desde el código fuente

git clone https://github.com/gerardbourguett/mcp-chilegob-dataset.git
cd mcp-chilegob-dataset
npm install

Scripts disponibles

| Comando | Descripción | |---------|-------------| | npm run dev | Inicia el servidor HTTP en http://localhost:3000/mcp con recarga automática | | npm run build | Compila TypeScript a dist/ | | npm start | Inicia el servidor HTTP desde dist/ | | npm run typecheck | Verifica tipos sin compilar |

Probar localmente (MCP Inspector)

Con el servidor corriendo (npm run dev), abre otra terminal y ejecuta:

npx @modelcontextprotocol/inspector

Se abre una interfaz web en http://localhost:6274. Configura:

• Transport type: Streamable HTTP
• URL: http://localhost:3000/mcp

Desde ahí puedes llamar a cualquier herramienta de forma interactiva y ver las respuestas.

Arquitectura

Cliente AI  →  Hono HTTP  →  McpServer  →  CKAN API v3 (datos.gob.cl)

src/
├── index.ts        # Servidor HTTP (para desarrollo y despliegue remoto)
├── stdio.ts        # Transporte stdio (para npx y Claude Desktop)
├── server.ts       # Instancia McpServer + registro de herramientas
├── ckan.ts         # Cliente tipado para la API CKAN v3
└── tools/
    ├── search.ts   # search_datasets
    ├── dataset.ts  # get_dataset
    └── resource.ts # get_resource_data

Cómo agregar nuevas herramientas

1. Crea src/tools/tu-herramienta.ts
2. Impórtala y regístrala en src/server.ts

// src/tools/tu-herramienta.ts
import type { McpServer } from '@modelcontextprotocol/server'
import { z } from 'zod'

export function registerTuHerramienta(server: McpServer): void {
  server.registerTool(
    'nombre_herramienta',
    {
      title: 'Nombre visible en el cliente',
      description: 'Descripción clara. El asistente la usa para decidir cuándo llamar esta herramienta.',
      inputSchema: z.object({
        parametro: z.string().describe('Descripción del parámetro'),
      }),
    },
    async ({ parametro }) => {
      // tu lógica aquí
      return {
        content: [{ type: 'text', text: JSON.stringify({ resultado: parametro }) }],
      }
    }
  )
}

Limitaciones conocidas

• Disponibilidad del datastore — No todos los recursos tienen datastore habilitado en CKAN. get_resource_data intenta automáticamente descargar el archivo (CSV, TSV, JSON); los formatos binarios (XLS, PDF) requieren descarga manual desde la URL devuelta.
• Archivos grandes — La descarga directa carga el archivo completo en memoria antes de paginar. Para archivos muy grandes (>100 MB) esto puede ser lento o fallar.
• Encoding — Los archivos CSV de datos.gob.cl pueden estar en ISO-8859-1 (Latin-1). La herramienta intenta leerlos como UTF-8; si los caracteres aparecen corruptos, descarga el archivo directamente.
• Caché en memoria (5 min) — search_datasets y get_dataset usan caché en memoria con TTL de 5 minutos. get_resource_data siempre consulta en vivo. No hay límites de tasa documentados en datos.gob.cl.
• Timeout de red (10s) — Todas las solicitudes a datos.gob.cl tienen un timeout de 10 segundos. Si el portal está lento o caído, las herramientas devuelven un error claro en lugar de colgar indefinidamente.
• Paquetes en alpha — @modelcontextprotocol/hono y @modelcontextprotocol/server están en versión alpha.

Contribuciones

Las contribuciones son bienvenidas. Algunas ideas:

• [ ] Herramienta list_organizations — listar instituciones disponibles
• [ ] Herramienta get_resource_schema — tipos y descripciones de columnas
• [ ] MCP Resources con URI templates (datos-gob-cl://dataset/{id})

Por favor, abre un issue antes de enviar un PR grande.

Licencia

MIT — ver LICENSE.