EcuDataMCP

# 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.