Content
# EcuDataMCP
Sitio: [https://dweskz.github.io/EcuDataMCP/](https://dweskz.github.io/EcuDataMCP/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://m8ven.ai/mcp/dweskz/ecudatamcp)
<!-- mcp-name: io.github.DweskZ/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](docs/ROADMAP.md)** — qué fuentes están integradas y qué falta.
- **[docs/RESEARCH.md](docs/RESEARCH.md)** — el porqué de cada fila del roadmap:
hallazgos verificados en vivo, dominios investigados, dead ends.
- **[CHANGELOG.md](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, Codex, 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](https://docs.astral.sh/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):
```json
{
"mcpServers": {
"ecuador-datos": {
"command": "uvx",
"args": ["ecuador-mcp", "--transport", "stdio"]
}
}
}
```
También puedes instalar el archivo `.mcpb` adjunto a cada
[release](https://github.com/DweskZ/EcuDataMCP/releases) como extensión de
Claude Desktop. Si ya tienes el servidor HTTP corriendo (ver
[Ejecutar localmente](#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:
```json
{
"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):
```json
{
"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
```bash
claude mcp add --transport http ecuador-datos http://localhost:8000/mcp
```
### Codex
```bash
codex mcp add ecuador-datos --url http://localhost:8000/mcp
```
Esto guarda un bloque `[mcp_servers.ecuador-datos]` con `url` en `~/.codex/config.toml`. Para usar el servidor por stdio en vez de HTTP:
```bash
codex mcp add ecuador-datos -- uvx ecuador-mcp --transport stdio
```
### Gemini CLI
Agrega a `~/.gemini/settings.json`:
```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`:
```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)
```bash
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:
```bash
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`:
```bash
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](https://docs.astral.sh/uv/).
```bash
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:
```bash
uv run python main.py --transport stdio
```
La referencia detallada de cada herramienta está en [docs/TOOLS.md](docs/TOOLS.md).
El contrato JSON para agentes de BCEData/IEM está en
[docs/RESPONSE_CONTRACT.md](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](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](LICENSE) para más detalles.
---
## Contribuir
Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](CONTRIBUTING.md)
para el proceso de colaboración.
Connection Info
You Might Also Like
No recommendations available