indec-mcp
by julianmantel
README.md
# indec-mcp
Servidor [MCP](https://modelcontextprotocol.io) de **solo lectura** que permite a asistentes de IA (Claude, Cursor, VS Code, OpenCode, Antigravity, etc.) consultar las estadísticas oficiales del **INDEC** (Argentina): inflación, actividad económica, canastas, pobreza, empleo, salarios y más.
> Proyecto **no oficial**, sin afiliación con el INDEC. Los datos pertenecen al Instituto Nacional de Estadística y Censos de la República Argentina.
Una vez instalado, podés preguntarle a tu asistente cosas como:
```text
Cuál fue la última inflación mensual publicada por el INDEC?
Comparame la inflación interanual de GBA y Patagonia durante 2024.
Cuánto cuesta hoy la canasta básica total? Y la de crianza para un niño de 1 a 3 años?
Mostrame la evolución de la desocupación en el Gran Buenos Aires desde 2022.
Qué datasets tiene la API del INDEC sobre comercio exterior?
```
## Índice
- [Inicio rápido](#inicio-rápido)
- [Instalación por cliente](#instalación-por-cliente)
- [Variables de entorno](#variables-de-entorno)
- [Herramientas disponibles](#herramientas-disponibles)
- [Solución de problemas](#solución-de-problemas)
- [Desarrollo](#desarrollo)
- [Arquitectura](#arquitectura)
- [Fuente de los datos](#fuente-de-los-datos)
## Inicio rápido
**Requisitos**
- Node.js **20.6 o superior** (`node -v`).
- Un cliente MCP (Claude Desktop, Claude Code, Cursor, VS Code, OpenCode, Antigravity u otro).
- Un **token JWT gratuito** de la API del INDEC. Solo hace falta para consultar datos: el catálogo (`indec_list_datasets`, `indec_describe_dataset`) funciona sin token.
**1. Obtené tu token**
1. Registrate en <https://api.indec.gob.ar>.
2. Verificá tu cuenta con el código OTP que llega por mail.
3. Generá el token JWT desde tu perfil. **Se muestra una sola vez**, guardalo. Vence a los 12 meses.
**2. Instalá y compilá el servidor**
```bash
git clone <repo-url>
cd indec-mcp
npm install
npm run build
```
Anotá la **ruta absoluta** al archivo compilado, la vas a necesitar en el paso siguiente:
```text
<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js
```
> En macOS/Linux podés obtenerla con `pwd` dentro de la carpeta del proyecto y agregando `/dist/index.js`.
> En Windows, usá barras normales (`C:/Users/vos/indec-mcp/dist/index.js`) o barras invertidas dobles (`C:\\Users\\vos\\indec-mcp\\dist\\index.js`) dentro del JSON.
**3. Conectalo a tu cliente**
Elegí tu cliente en la sección siguiente. Si no sabés cuál usar, el más directo es **Claude Code** (un solo comando) o **Claude Desktop** (un archivo JSON).
**4. Probalo**
Reiniciá el cliente y pedile algo simple:
```text
Usá el servidor indec y decime el estado de la conexión (indec_status).
```
Deberías ver `Token configurado: Sí`. Después probá una consulta real, por ejemplo la última inflación.
## Instalación por cliente
Todos los clientes necesitan lo mismo: el comando `node`, la ruta a `dist/index.js` y la variable `INDEC_API_TOKEN`. Lo que cambia es **dónde** se escribe y **cómo se llama la clave raíz** (`mcpServers`, `servers` o `mcp`).
| Cliente | Dónde se configura | Clave raíz |
| --------------- | ------------------------------------------ | ------------ |
| Claude Code | Comando `claude mcp add` | - |
| Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
| Cursor | `~/.cursor/mcp.json` o `.cursor/mcp.json` | `mcpServers` |
| VS Code | `.vscode/mcp.json` | `servers` |
| OpenCode | `opencode.json` | `mcp` |
| Antigravity | `mcp_config.json` (desde la UI) | `mcpServers` |
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add indec --env INDEC_API_TOKEN=<tu_token> -- node <RUTA_AL_PROYECTO>/indec-mcp/dist/index.js
```
Verificá con `claude mcp list`. Dentro de Claude Code, el comando `/mcp` muestra el estado de cada servidor.
</details>
<details>
<summary><b>Claude Desktop</b></summary>
Abrí **Settings → Developer → Edit Config**, o editá el archivo directamente:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"indec": {
"command": "node",
"args": ["<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"],
"env": {
"INDEC_API_TOKEN": "<tu_token>"
}
}
}
}
```
Guardá y **reiniciá Claude Desktop por completo**. Las herramientas aparecen en el ícono de herramientas del chat.
</details>
<details>
<summary><b>Cursor</b></summary>
Abrí **Settings → Cursor Settings → MCP → Add new global MCP server**, o editá `~/.cursor/mcp.json` (global) o `.cursor/mcp.json` (solo el proyecto actual):
```json
{
"mcpServers": {
"indec": {
"command": "node",
"args": ["<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"],
"env": {
"INDEC_API_TOKEN": "<tu_token>"
}
}
}
}
```
</details>
<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>
Creá `.vscode/mcp.json` en tu workspace. VS Code usa la clave `servers` (no `mcpServers`) y exige `type`. Para no dejar el token escrito en el archivo, podés pedirlo al iniciar con `inputs`:
```json
{
"inputs": [
{
"type": "promptString",
"id": "indec-token",
"description": "Token JWT de la API del INDEC",
"password": true
}
],
"servers": {
"indec": {
"type": "stdio",
"command": "node",
"args": ["<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"],
"env": {
"INDEC_API_TOKEN": "${input:indec-token}"
}
}
}
}
```
</details>
<details>
<summary><b>OpenCode</b></summary>
OpenCode define los servidores directamente bajo `mcp`, con `command` como **arreglo** y las variables en `environment`. Editá `opencode.json` (en el proyecto) o `~/.config/opencode/opencode.json` (global):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"indec": {
"type": "local",
"command": ["node", "<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"],
"enabled": true,
"environment": {
"INDEC_API_TOKEN": "<tu_token>"
}
}
}
}
```
Verificá con `opencode mcp list`. Para usarlo, mencioná el servidor en el prompt (por ejemplo: *"…usá indec"*).
</details>
<details>
<summary><b>Google Antigravity</b></summary>
1. En el panel del agente abrí el menú **⋯ → MCP Servers → Manage MCP Servers**.
2. Hacé clic en **View raw config** (abre `mcp_config.json`; la ubicación del archivo puede variar según la versión, por eso conviene abrirlo desde la interfaz).
3. Agregá el servidor:
```json
{
"mcpServers": {
"indec": {
"command": "node",
"args": ["<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"],
"env": {
"INDEC_API_TOKEN": "<tu_token>"
}
}
}
}
```
4. Guardá y recargá el panel de MCP: `indec` debería aparecer con sus herramientas.
</details>
<details>
<summary><b>Otro cliente MCP</b></summary>
Cualquier cliente compatible con transporte **stdio** funciona. Necesita:
- **Comando:** `node`
- **Argumentos:** `<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js`
- **Variable de entorno:** `INDEC_API_TOKEN=<tu_token>`
</details>
### Alternativa: token desde un archivo `.env`
Si preferís no escribir el token en la configuración del cliente (por ejemplo, porque ese archivo se sincroniza o se comparte), guardalo en un `.env` y pasalo con el flag `--env-file` de Node:
```bash
cp .env.example .env
# editá .env y completá INDEC_API_TOKEN
```
Después reemplazá el comando del cliente por:
```json
{
"command": "node",
"args": [
"--env-file=<RUTA_AL_PROYECTO>/indec-mcp/.env",
"<RUTA_AL_PROYECTO>/indec-mcp/dist/index.js"
]
}
```
> `.env.example` es solo una plantilla: el servidor **no** carga archivos `.env` por sí solo. El token se lee únicamente si la variable está en el entorno del proceso o si se usa `--env-file`. Esta opción requiere Node.js 20.6+.
## Variables de entorno
| Variable | Obligatoria | Por defecto | Descripción |
| -------------------------- | :---------: | ------------------------------ | ----------------------------------------------------------------------------- |
| `INDEC_API_TOKEN` | Para datos | - | Token JWT de la API del INDEC. |
| `INDEC_API_BASE_URL` | No | `https://api.indec.gob.ar/v1/` | URL base de la API. Solo se acepta HTTPS o `localhost`. |
| `INDEC_API_ALLOWED_HOSTS` | No | `api.indec.gob.ar`, loopback | Hosts permitidos para la URL base, separados por coma y sin puerto. |
| `INDEC_CACHE_TTL_SECONDS` | No | `3600` | Vida de la caché en memoria, en segundos. `0` la desactiva. |
| `INDEC_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout por solicitud HTTP, en milisegundos. |
## Herramientas disponibles
El flujo recomendado para consultas libres es: **listar → describir → consultar**. Las herramientas temáticas (`indec_get_*`) ya traen los filtros resueltos para los indicadores más usados.
### Catálogo (sin token)
| Herramienta | Descripción |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `indec_status` | Estado del servidor, si el token está configurado y si el spec remoto cambió respecto al snapshot. |
| `indec_list_datasets` | Catálogo de datasets con identificador, área, frecuencia y resumen. |
| `indec_describe_dataset` | Columnas, tipos, nulabilidad, claves de orden y dimensiones temporales de un dataset. |
### Consultas genéricas (requieren token)
| Herramienta | Descripción |
| --------------------- | ---------------------------------------------------------------------------------- |
| `indec_query_dataset` | Consulta con `select`, `filters`, `order`, `limit` (máx. 1000) y `offset`. |
| `indec_count_rows` | Total exacto de filas, con filtros opcionales, sin transferir el dataset completo. |
### Indicadores temáticos (requieren token)
Si no indicás fechas, devuelven **solo el último período publicado**.
| Herramienta | Descripción |
| --------------------------- | --------------------------------------------------------------------- |
| `indec_get_ipc` | IPC e inflación: nivel general o divisiones, por región y variación. |
| `indec_get_emae` | EMAE a nivel general o desagregado por sectores de actividad. |
| `indec_get_canastas` | Canastas Básicas Alimentaria (CBA) y Total (CBT). |
| `indec_get_canasta_crianza` | Canasta de crianza por tramos de edad. |
| `indec_get_mercado_trabajo` | Tasas de actividad, empleo, desocupación y subocupación (EPH). |
| `indec_get_pobreza` | Incidencia de pobreza e indigencia en personas y hogares (EPH). |
| `indec_get_salarios` | Índice de Salarios por sector y tipo de indicador. |
## Solución de problemas
| Síntoma | Causa probable y solución |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| El servidor no aparece o figura como desconectado | Falta compilar (`npm run build`), la ruta a `dist/index.js` no es **absoluta** o tiene errores de escapado en Windows. Reiniciá el cliente tras editar la config. |
| `Error de autenticación` / `Token no configurado` | `INDEC_API_TOKEN` no llegó al proceso. Revisá el bloque `env` (u `environment` en OpenCode) o la ruta de `--env-file`. `indec_status` te lo confirma. |
| Error 401 al consultar | El token es inválido o venció (duran 12 meses). Generá uno nuevo en <https://api.indec.gob.ar>. |
| Error 429 | Límite de solicitudes de la API. Esperá unos segundos; el servidor ya reintenta automáticamente con espera creciente. |
| `node: bad option: --env-file` | Tu Node es anterior a 20.6. Actualizalo o usá el bloque `env` del cliente. |
| Falla en OpenCode con la config copiada de otro cliente | OpenCode usa `mcp` → nombre → `type`/`command` (arreglo)/`environment`. No acepta `mcpServers` ni `env`. |
| Antigravity registra el servidor pero no hay herramientas | Revisá el JSON en *View raw config* y recargá el panel MCP. Para servidores locales se usa `command`/`args`/`env`. |
| Resultados incompletos o columnas que no existen | La API del INDEC está en **BETA** y puede cambiar. Ejecutá `indec_status` para ver si el spec remoto difiere y consultá `indec_describe_dataset`. |
Para depurar de forma aislada, abrí el servidor en el inspector oficial de MCP (reemplazá el token):
```bash
INDEC_API_TOKEN=<tu_token> npx @modelcontextprotocol/inspector node dist/index.js
```
Los logs del servidor salen por `stderr`; `stdout` está reservado al protocolo MCP.
## Desarrollo
```bash
npm install
npm run gen # regenera el registry desde docs/openapi.snapshot.json
npm run gen -- --fetch # descarga el spec actualizado del INDEC y regenera
npm run build # compila a dist/
npm run dev # ejecuta con tsx (sin compilar)
npm test # tests con vitest (ninguno llama a la API real)
npm run lint # eslint + prettier
```
Notas:
- `src/datasets/registry.generated.ts` es un archivo generado: **no se edita a mano**.
- Los tests usan `fetch` simulado; ninguno requiere token ni red.
- Las convenciones del proyecto y las reglas para agentes de código están en [`AGENTS.md`](./AGENTS.md).
## Arquitectura
```text
src/
├── index.ts # composition root (stdio)
├── server.ts # registro de las 12 herramientas MCP
├── container.ts # construcción de cliente, registry y servicio
├── config.ts # variables de entorno validadas con zod
├── client/
│ ├── transport.ts # autenticación, timeout y reintentos
│ ├── indec-client.ts # transporte, caché y PostgREST
│ ├── postgrest.ts # construcción de parámetros de consulta
│ ├── cache.ts # caché en memoria con TTL y límite de entradas
│ └── errors.ts # errores de dominio y mapeo de estados HTTP
├── datasets/
│ ├── types.ts # tipos de datasets y columnas
│ ├── registry.ts # búsqueda, obtención y sugerencias
│ └── registry.generated.ts # archivo generado desde el snapshot OpenAPI
├── services/
│ ├── dataset-query.ts # validación y ejecución de consultas
│ ├── latest-period.ts # resolución del último período publicado
│ └── period-filters.ts # filtros de período de las herramientas curadas
└── tools/
├── context.ts # contexto inyectado en las herramientas
├── presentation.ts # formato de respuestas y advertencias
├── errors.ts # presentación de errores
├── meta.ts # status, list y describe
├── query.ts # query y count genéricos
└── curated/ # herramientas por tema
```
## Casos de uso
### 1. Perfil regional para focalizar programas
**Situación:** un organismo público o un equipo de investigación necesita un panorama actualizado de pobreza, empleo y costo de vida para un informe o una presentación.
**Prompt pasado el agente**
```text
Preparame un tablero de situación social con el último semestre publicado:
pobreza e indigencia (personas y hogares) con su variación contra el semestre
anterior, la desocupación del período más cercano y el costo de la canasta
básica total para un hogar de 4 integrantes. Indicá el período de cada dato
y si está marcado como provisorio.
```
**Qué hace el servidor:** consulta pobreza, mercado de trabajo y canastas (`indec_get_pobreza`, `indec_get_mercado_trabajo`, `indec_get_canastas`).
**Resultado:** una tabla con el valor de cada indicador, su variación y su período, con las observaciones de la fuente (por ejemplo, datos provisorios).
### 2. Series con fuente verificable para investigación y periodismo
**Situación:** una nota o un trabajo académico requiere datos con origen verificable y mencionar qué dataset se usó.
**Prompt pasado el agente**
```text
Listá los datasets del INDEC relacionados con comercio exterior, describí las
columnas del más relevante y traé la serie de los últimos 5 años.
Indicá el nombre exacto del dataset y los filtros aplicados para que pueda
citarlo.
```
**Qué hace el servidor:** recorre el catálogo y la estructura de los datasets (`indec_list_datasets`, `indec_describe_dataset`) y ejecuta la consulta (`indec_query_dataset`).
**Resultado:** serie con nombre de dataset, filtros y período, para citar y reproducir.
## Fuente de los datos
Fuente: INDEC - Catálogo API-INDEC, <https://api.indec.gob.ar>.
Este proyecto solo facilita el acceso a la API pública y no modifica ni reinterpreta las cifras oficiales.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues