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 Desktop (recomendado)

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 estas líneas:

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

Paso 3 — Reinicia Claude Desktop. La primera vez descarga el paquete automáticamente.

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:

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:

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:

Parámetros:

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

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.