EcuDataMCP

EcuDataMCP

Infraestructura abierta de datos públicos para Ecuador. EcuDataMCP conecta asistentes de IA, investigadores, periodistas y software con datos oficiales ecuatorianos mediante una interfaz común.

Utiliza el Model Context Protocol (MCP) para que clientes compatibles como Claude, ChatGPT, Gemini y Cursor puedan buscar, explorar y analizar esos datos mediante conversación o software.

En lugar de navegar manualmente por portales gubernamentales, simplemente pregunta cosas como:

• "¿Qué datos tiene el SRI sobre recaudación tributaria?"
• "Muéstrame los datasets de salud del INEC"
• "¿Cuáles son los requisitos para sacar el pasaporte?"
• "Dame un preview de los datos de transporte aéreo"

Aviso: Las definiciones, parámetros y descripciones de algunas herramientas fueron generadas o asistidas por IA y pueden estar incompletas, desactualizadas o no cubrir todos los casos del endpoint subyacente. Una herramienta puede devolver resultados parciales, rechazar parámetros válidos o comportarse de forma inesperada cuando cambia la fuente oficial. Verifica siempre la respuesta contra la fuente enlazada y revisa manualmente los resultados antes de usarlos para decisiones importantes.

---

Documentación del proyecto

• docs/ROADMAP.md — qué fuentes están integradas y qué falta.
• docs/RESEARCH.md — el porqué de cada fila del roadmap: hallazgos verificados en vivo, dominios investigados, dead ends.
• CHANGELOG.md — qué se publicó recientemente.

---

Beneficios

• Acceso instantáneo a datos públicos: Pregunta en lenguaje natural y explora datos de instituciones del Estado ecuatoriano sin navegar portales, descargar archivos ni lidiar con formatos.
• Unifica múltiples fuentes en un solo punto: Datos abiertos, trámites, regulaciones, contratación pública, riesgos, datos estadísticos y otras fuentes oficiales, todo accesible desde una sola conversación con tu IA.
• Preview de datos sin descargas: preview_resource_data parsea CSV/TSV, JSON/GeoJSON, Excel (XLS/XLSX) y algunos archivos comprimidos en memoria; query_resource_data consulta el DataStore CKAN sin bajar el archivo completo.
• Cero fricción: No necesitas API key ni permisos especiales para las fuentes públicas compatibles.
• Compatible con cualquier cliente MCP: Claude, ChatGPT, Gemini, Cursor, VS Code, Windsurf, Le Chat, HuggingChat y más.
• Listo para producción: Docker, health checks, logging estructurado, y un servidor HTTP Streamable compatible con MCP.

---

Casos de uso

Para ciudadanos

• Consultar requisitos, costos y pasos de cualquier trámite gubernamental sin navegar gob.ec.
• Buscar datos públicos por tema (salud, educación, seguridad, economía) y entender qué publica cada institución.

Para periodistas e investigadores

• Explorar datasets del catálogo nacional y hacer preview de los datos directamente desde Claude o ChatGPT.
• Cruzar información de múltiples instituciones (SRI, INEC, BCE y ministerios) en una sola conversación.
• Acceder rápidamente a datos de anticorrupción, presupuestos y ejecución del gasto público.

Para desarrolladores

• Integrar datos abiertos de Ecuador en aplicaciones mediante el protocolo MCP estándar.
• Prototipar dashboards y análisis exploratorios sin escribir código de scraping ni parseo de archivos.
• Usar como backend de datos para agentes de IA que necesiten contexto sobre Ecuador.

Para el sector público

• Hacer más accesibles y descubribles los datos que ya publican las instituciones.
• Permitir que chatbots institucionales respondan preguntas con datos reales y actualizados.
• Demostrar el valor de los datos abiertos conectándolos directamente con herramientas de IA.

---

Fuentes de datos

Este MCP unifica fuentes gubernamentales en un solo servidor:

Fuente	Datos
Datos Abiertos y Cuenca en Datos (CKAN)	Catálogos, DataStore y archivos públicos
SRI	Datasets estadísticos, recaudación, RUC y Saiku público
Gob.ec	Trámites, instituciones y regulaciones
SERCOP/OCDS	Contratación pública
SGR e IG-EPN	Eventos de riesgo, tsunami y sismos
INEC	ANDA, Ecuador en Cifras, censos y recursos estadísticos
BCE	BCEData, IEM y otros indicadores económicos públicos
Superintendencia de Compañías	Directorio, auditores y datos financieros
Geografía INEC/DPA	Provincias, cantones y parroquias

Sin API key para las fuentes públicas compatibles.

---

Conecta tu chatbot al servidor MCP

Claude Desktop

La forma más simple no necesita levantar ningún servidor: Claude Desktop ejecuta el paquete de PyPI con uv. Agrega lo siguiente a tu archivo de configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "ecuador-datos": {
      "command": "uvx",
      "args": ["ecuador-mcp", "--transport", "stdio"]
    }
  }
}

También puedes instalar el archivo .mcpb adjunto a cada release como extensión de Claude Desktop. Si ya tienes el servidor HTTP corriendo (ver Ejecutar localmente), usa "command": "npx" con "args": ["mcp-remote", "http://localhost:8000/mcp"].

Cursor

1. Abre Cursor Settings
2. Busca "MCP"
3. Agrega un nuevo servidor MCP:

{
  "mcpServers": {
    "ecuador-datos": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

VS Code

Agrega a tu archivo mcp.json (ejecuta MCP: Open User Configuration desde la paleta de comandos):

{
  "servers": {
    "ecuador-datos": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}

ChatGPT

Disponible para planes pagos (Plus, Pro, Team, Enterprise).

1. Ve a Settings > Apps and connectors
2. Abre Advanced settings y habilita Developer mode
3. En Settings > Connectors > Browse connectors, haz clic en Add a new connector
4. Configura la URL: http://localhost:8000/mcp

Claude Code

claude mcp add --transport http ecuador-datos http://localhost:8000/mcp

Gemini CLI

Agrega a ~/.gemini/settings.json:

{
  "mcpServers": {
    "ecuador-datos": {
      "httpUrl": "http://localhost:8000/mcp"
    }
  }
}

Le Chat (Mistral)

1. Ve a Intelligence > Connectors
2. Add connector > Custom MCP Connector
3. Nombre: "Ecuador Datos" / URL: http://localhost:8000/mcp

Windsurf

Agrega a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ecuador-datos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

HuggingChat

1. En el chat, haz clic en el ícono + > MCP Servers > Manage MCP Servers
2. Add Server con nombre "Ecuador Datos" y URL http://localhost:8000/mcp

---

Ejecutar localmente

Con uvx (desde PyPI)

uvx ecuador-mcp --transport stdio

search_ranking/get_financials usan una base SQLite local de Supercías que se construye sola en segundo plano cuando la primera consulta la necesita (descarga ~356 MB, 5-10 min; esa consulta pide reintentar). Instalado desde PyPI se guarda en el directorio de datos del usuario (%LOCALAPPDATA%\ecuador-mcp en Windows, ~/Library/Application Support/ecuador-mcp en macOS, ~/.local/share/ecuador-mcp en Linux); ECUADOR_MCP_DATA_DIR cambia la ubicación.

Con Docker (recomendado)

La imagen arranca por stdio, como cualquier servidor MCP en Docker:

docker build -t ecuador-mcp https://github.com/DweskZ/EcuDataMCP.git
docker run -i --rm ecuador-mcp

Para el servidor HTTP, docker compose fija MCP_TRANSPORT=http:

git clone https://github.com/DweskZ/EcuDataMCP.git
cd EcuDataMCP

# Iniciar con configuración por defecto (puerto 8000)
docker compose up -d

# Con variables personalizadas
MCP_PORT=8007 LOG_LEVEL=DEBUG docker compose up -d

# Detener
docker compose down

Instalación manual

Requiere Python 3.11+ y uv.

git clone https://github.com/DweskZ/EcuDataMCP.git
cd EcuDataMCP

# Instalar dependencias
uv sync

# Copiar variables de entorno
cp .env.example .env

# Iniciar el servidor
uv run main.py

Variables de entorno:

Variable	Descripción	Default
MCP_HOST	Dirección de bind	127.0.0.1
MCP_PORT	Puerto del servidor	8000
MCP_TRANSPORT	Transporte: http o stdio	http
LOG_LEVEL	Nivel de log (DEBUG, INFO, WARNING, ERROR)	INFO
MCP_AUTH_TOKEN	Token Bearer opcional para /mcp	vacío
MCP_REQUIRE_AUTH	Rechaza el arranque remoto sin token	0
MCP_RATE_LIMIT_REQUESTS / MCP_RATE_LIMIT_WINDOW_SECONDS	Cuota por cliente/IP	120 / 60
MCP_SSL_CERTFILE / MCP_SSL_KEYFILE	Certificado y clave para TLS directo	vacío
ECUADOR_MCP_USAGE_LOG	1 guarda cada llamada (tool, resultado, duración; nunca argumentos) en usage.jsonl del directorio de datos; scripts/usage_report.py lo resume	vacío
ECUADOR_MCP_DATA_DIR	Dónde guardar la base de Supercías y los snapshots del BCE	data/ en un clon; directorio de datos del usuario si se instaló desde PyPI

Para ejecutar el transporte stdio localmente:

uv run python main.py --transport stdio

La referencia detallada de cada herramienta está en docs/TOOLS.md. El contrato JSON para agentes de BCEData/IEM está en docs/RESPONSE_CONTRACT.md.

---

Endpoints

Endpoint	Descripción
POST /mcp	Mensajes JSON-RPC (cliente → servidor)
GET /health	Health check: {"status":"ok","uptime_since":"...","version":"..."}
GET /usage	Llamadas, errores y latencia p50/p95 por tool desde el arranque

Cuando MCP_AUTH_TOKEN está definido, POST /mcp requiere el encabezado Authorization: Bearer <token>. Para un despliegue remoto usa también MCP_REQUIRE_AUTH=1, HTTPS y un proxy con su propia cuota por IP. /health y /usage permanecen sin autenticación (no exponen argumentos ni datos de usuarios). Consulta docs/DEPLOYMENT.md para el despliegue remoto.

---

Ejemplos de uso

Buscar datos del SRI

"¿Qué datos tiene el SRI sobre recaudación?"

El MCP buscará los datos públicos del SRI y te mostrará los resultados con títulos, descripciones y enlaces.

Ver datos de salud

"Muéstrame un preview de los datos de hospitales"

El MCP descargará el archivo compatible y te mostrará las primeras filas como una tabla formateada.

Consultar trámites

"¿Cuáles son los requisitos para obtener el RUC?"

El MCP buscará en el portal gob.ec y te dará los requisitos, procedimiento y costo.

Explorar por categoría

"¿Qué categorías de datos hay disponibles?"

El MCP listará las categorías temáticas disponibles.

---

Arquitectura

Cliente MCP (Claude, ChatGPT, Cursor, etc.)
    │
    ▼ POST /mcp
┌──────────────────────────────┐
│   MCPServer (main.py)        │
├──────────────────────────────┤
│  tools/                      │
│   ├── search_ecuador         │  → CKAN + gob.ec (unificado)
│   ├── search_datasets        │
│   ├── query_resource_data    │  → CKAN DataStore
│   ├── preview_resource_data  │  → CSV / JSON / XLS / XLSX
│   ├── get_category_info      │  → helpers/ckan_client.py
│   ├── search_tramites        │
│   ├── get_institucion_info   │  → helpers/gobec_client.py
│   └── ...                    │
└──────────────────────────────┘

---

Licencia

MIT License - ver LICENSE para más detalles.

---

Contribuir

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para el proceso de colaboración.