Open Data Spain MCP

MCP que unifica el acceso a las principales fuentes de datos abiertos de España (BOE, INE, AEMET, Datos.gob.es)

Documentación

datos-gob-es-mcp

Hub de OpenData Español - Servidor MCP (Model Context Protocol) que unifica el acceso a las principales fuentes de datos abiertos de España en una sola interfaz.

Descripción

Este servidor MCP actúa como un hub centralizado que conecta múltiples APIs de datos públicos españoles, permitiendo a asistentes de IA como Claude, ChatGPT y otros clientes MCP acceder a toda la información desde un único punto.

Fuentes de datos integradas

Fuente	Descripción	Auth	Documentación
datos.gob.es	Catálogo nacional de datos abiertos (+40.000 datasets)	No	API
INE	Instituto Nacional de Estadística	No	API
AEMET	Agencia Estatal de Meteorología	API key	API
BOE	Boletín Oficial del Estado	No	API

Características

11 herramientas MCP simplificadas para consultar múltiples APIs de datos públicos
5 recursos MCP (templates dinámicos) para acceso directo a datos
6 prompts MCP para guías de búsqueda detalladas
Búsqueda semántica: Búsqueda por significado usando embeddings (IA)
Caché de metadatos: Caché local de 24h para respuestas instantáneas
Paginación paralela: Descarga 5x más rápida con fetch_all=True
Descarga integrada: get(id, include_data=true) en una sola llamada
Búsqueda AEMET por nombre: Usa nombres de municipio directamente (ej: "Madrid")
Retry automático: Reintentos con backoff exponencial para mayor resiliencia
Sinónimos INE: Expansión de consultas para mejores resultados
Cliente HTTP asíncrono con rate limiting por API
Modelos Pydantic para tipado seguro
Listo para desplegar en FastMCP Cloud

Instalación

Requisitos

Python 3.10 o superior
pip

Instalación rápida

# Clonar el repositorio
git clone https://github.com/AlbertoUAH/datos-gob-es-mcp.git
cd datos-gob-es-mcp

# Crear entorno virtual e instalar
make dev

Instalación manual

# Crear entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

Configuración

Variables de entorno

Crea un archivo .env basándote en .env.example:

cp .env.example .env

Variable	Requerida	Descripción
`AEMET_API_KEY`	Para meteorología	API key de AEMET OpenData (obtener gratis)
`PRELOAD_EMBEDDINGS_MODEL`	No	Pre-cargar modelo de embeddings en startup (default: true)
`LOG_LEVEL`	No	Nivel de logging: DEBUG, INFO, WARNING, ERROR (default: INFO)
`LOG_FORMAT`	No	Formato de logs: console o json (default: console)
`RATE_LIMIT_DATOS_GOB_ES`	No	Peticiones/segundo a datos.gob.es (default: 10)
`RATE_LIMIT_INE`	No	Peticiones/segundo a INE (default: 5)
`RATE_LIMIT_AEMET`	No	Peticiones/segundo a AEMET (default: 10)
`RATE_LIMIT_BOE`	No	Peticiones/segundo a BOE (default: 10)

Uso

Ejecutar el servidor MCP

# Modo stdio (para clientes MCP)
make run-stdio

# O directamente
mcp run server.py

Inspeccionar herramientas disponibles

make inspect

Arquitectura

flowchart TB
    subgraph Cliente["Cliente MCP"]
        ChatGPT["ChatGPT"]
    end

    subgraph MCP["Servidor MCP (FastMCP)"]
        Server["server.py"]
    end

    ChatGPT <-->|"Protocolo MCP"| Server

    subgraph Tools["TOOLS (11)"]
        subgraph ToolsDatosGob["datos.gob.es (2)"]
            search
            get
        end

        subgraph ToolsINE["INE (2)"]
            ine_search
            ine_download
        end

        subgraph ToolsAEMET["AEMET (3)"]
            aemet_list_locations
            aemet_get_observations
            aemet_get_forecast
        end

        subgraph ToolsBOE["BOE (3)"]
            boe_get_summary
            boe_get_document
            boe_search
        end
    end

    subgraph Resources["RESOURCES (5)"]
        R1["dataset://{id}"]
        R2["theme://{id}"]
        R3["publisher://{id}"]
        R4["format://{id}"]
        R5["keyword://{keyword}"]
    end

    subgraph Prompts["PROMPTS (6)"]
        P1["buscar_datos_por_tema"]
        P2["datasets_recientes"]
        P3["explorar_catalogo"]
        P4["analisis_dataset"]
        P5["guia_herramientas"]
        P6["buscar_estadisticas"]
    end

    Server --> Tools
    Server --> Resources
    Server --> Prompts

    subgraph APIs["APIs Externas"]
        API1["datos.gob.es"]
        API2["INE"]
        API3["AEMET"]
        API4["BOE"]
    end

    ToolsDatosGob --> API1
    Resources --> API1
    ToolsINE --> API2
    ToolsAEMET --> API3
    ToolsBOE --> API4

Capacidades MCP

Capacidad	Cantidad	Descripción
Tools	11	Funciones que el LLM puede invocar
Resources	5	Templates dinámicos para acceso directo
Prompts	6	Guías de búsqueda predefinidas

Tools (Herramientas)

datos.gob.es (2 herramientas)

Herramienta	Descripción
`search`	Búsqueda unificada de datasets: por filtros (título, tema, publicador, formato, fecha), semántica (IA con embeddings) o híbrida. Soporta multi-tema con lógica OR y paginación paralela
`get`	Obtiene metadatos de un dataset y opcionalmente descarga sus datos. Con `include_data=true` descarga y parsea CSV/JSON (hasta 50MB)

INE - Instituto Nacional de Estadística (2 herramientas) - FUENTE PRINCIPAL DE ESTADÍSTICAS

El INE es la fuente oficial principal de estadísticas en España. Contiene datos de empleo (EPA), población, precios (IPC), PIB, turismo, censos, y más.

Herramienta	Descripción
`ine_search`	Busca operaciones estadísticas o lista tablas. Usa `query` para buscar operaciones, `operation_id` para listar tablas
`ine_download`	Obtiene datos estadísticos reales de una tabla del INE

AEMET - Meteorología (3 herramientas)

Herramienta	Descripción
`aemet_list_locations`	Lista municipios y/o estaciones meteorológicas. Usa `location_type` para filtrar
`aemet_get_observations`	Obtiene observaciones meteorológicas actuales de una estación
`aemet_get_forecast`	Obtiene la predicción meteorológica para un municipio (acepta nombre o código)

BOE - Boletín Oficial del Estado (3 herramientas)

Herramienta	Descripción
`boe_get_summary`	Obtiene el sumario del BOE. Si no se especifica fecha, devuelve el BOE más reciente
`boe_get_document`	Obtiene metadatos completos de un documento del BOE por su ID
`boe_search`	Busca documentos en el BOE por texto en un rango de fechas

Referencia de IDs

Los IDs de temas, publicadores y provincias están incluidos en las instrucciones del servidor MCP.

Temas (usar con `theme=`)

economia, hacienda, educacion, salud, medio-ambiente, transporte, turismo, empleo, sector-publico, ciencia-tecnologia, cultura-ocio, urbanismo-infraestructuras, energia

Publicadores principales (usar con `publisher=`)

ID	Organización
EA0010587	INE (Instituto Nacional de Estadística)
E05024401	Ministerio de Hacienda
E05024301	Ministerio de Economía
E00003901	AEMET
L01280796	Ayuntamiento de Madrid
L01080193	Ajuntament de Barcelona

Resources (Recursos)

Templates dinámicos para acceso directo a datos de datos.gob.es:

URI Template	Descripción	Ejemplo
`dataset://{dataset_id}`	Información de un dataset	`dataset://l01280066-presupuestos`
`theme://{theme_id}`	Datasets de una temática	`theme://economia`
`publisher://{publisher_id}`	Datasets de un publicador	`publisher://E00003901`
`format://{format_id}`	Datasets en un formato	`format://csv`
`keyword://{keyword}`	Datasets con una palabra clave	`keyword://presupuestos`

Prompts (Guías de Búsqueda)

Los prompts proporcionan guías estructuradas para tareas comunes de búsqueda:

Prompt	Descripción
`buscar_datos_por_tema`	Búsqueda guiada de datasets por temática y formato
`datasets_recientes`	Encontrar datasets actualizados en los últimos días
`explorar_catalogo`	Exploración guiada del catálogo de datos abiertos
`analisis_dataset`	Análisis detallado de un dataset específico
`guia_herramientas`	Documentación de todas las herramientas MCP
`buscar_estadisticas`	Búsqueda de estadísticas oficiales consultando INE y datos.gob.es

Ejemplos de Uso

Buscar datasets por texto

Usuario: Busca datasets sobre empleo en Andalucia
Asistente: [Usa search(title="empleo Andalucia")]

Buscar por significado (semántica)

Usuario: Encuentra datos sobre desempleo juvenil
Asistente: [Usa search(query="desempleo juvenil")]

Buscar por múltiples temas

Usuario: Busca datasets de economia o hacienda
Asistente: [Usa search(themes=["economia", "hacienda"])]

Obtener y descargar datos en una sola llamada

Usuario: Descarga los datos del dataset de presupuestos
Asistente: [Usa get(dataset_id="l01280066-presupuestos", include_data=true)]

Buscar estadísticas del INE

Usuario: Busca estadisticas sobre empleo
Asistente: [Usa ine_search(query="empleo")]
           -> Obtiene operacion EPA (id: 30308)
           [Usa ine_search(operation_id="30308")]
           -> Lista tablas disponibles
           [Usa ine_download(table_id="4247", n_last=12)]
           -> Obtiene datos reales

Obtener el BOE más reciente

Usuario: Dame el BOE de hoy
Asistente: [Usa boe_get_summary()]

Usuario: Dame el BOE del 2 de enero de 2025
Asistente: [Usa boe_get_summary(date="20250102")]

Obtener predicción meteorológica

Usuario: Que tiempo hara manana en Madrid?
Asistente: [Usa aemet_get_forecast(location="Madrid")]

Usuario: Que tiempo hara en Sevilla?
Asistente: [Usa aemet_get_forecast(location="Sevilla")]

Nota: aemet_get_forecast acepta tanto nombres de municipio como códigos (ej: "28079" para Madrid).

Configuración en Clientes MCP

Claude Desktop

Añade a tu archivo de configuración claude_desktop_config.json:

{
  "mcpServers": {
    "datos-gob-es": {
      "command": "mcp",
      "args": ["run", "/ruta/a/datos-gob-es-mcp/server.py"]
    }
  }
}

Desarrollo

Comandos disponibles

make help          # Mostrar ayuda
make dev           # Instalar en modo desarrollo
make run           # Ejecutar servidor
make run-stdio     # Ejecutar en modo stdio
make inspect       # Inspeccionar herramientas MCP
make test          # Ejecutar tests
make lint          # Verificar codigo con ruff
make format        # Formatear codigo con ruff
make clean         # Limpiar archivos de cache
make notebooks     # Iniciar servidor Jupyter

# Benchmark de latencia
python scripts/latency_benchmark.py

Estructura del proyecto

datos-gob-es-mcp/
├── server.py                 # Servidor MCP principal
├── core/                     # Modulo central
│   ├── logging.py           # Logging estructurado (structlog)
│   ├── ratelimit.py         # Rate limiting (aiolimiter)
│   ├── config.py            # Configuracion centralizada
│   └── http.py              # Cliente HTTP centralizado
├── integrations/             # APIs externas
│   ├── ine.py               # Instituto Nacional de Estadistica
│   ├── aemet.py             # Agencia de Meteorologia
│   └── boe.py               # Boletin Oficial del Estado
├── prompts/                  # Guias de busqueda MCP
├── scripts/                  # Scripts de utilidad
│   └── latency_benchmark.py # Benchmark de latencia
├── examples/                 # Jupyter notebooks de ejemplo
├── tests/                    # Tests automatizados
├── docs/                     # Documentacion adicional
│   └── latency_report.md    # Informe de latencia
├── requirements.txt         # Dependencias Python
├── Makefile                 # Comandos de desarrollo
└── README.md

Rendimiento

Latencia por herramienta

Tool	Latencia Promedio	Clasificación
`boe_get_summary`	54 ms	🟢 Rápido
`get` (metadata)	80 ms	🟢 Rápido
`search` (título)	127 ms	🟢 Rápido
`boe_search`	142 ms	🟢 Rápido
`search` (tema)	174 ms	🟢 Rápido
`ine_download`	197 ms	🟢 Rápido
`search` (keyword)	805 ms	🟡 Moderado
`ine_search`	1,368 ms	🟡 Moderado
`search` (semántica)	125 ms*	🟢 Rápido

* Con PRELOAD_EMBEDDINGS_MODEL=true (habilitado por defecto). Ver informe completo.

Optimizaciones implementadas

Mejora	Descripción	Impacto
Pre-carga de embeddings	Modelo ML se carga en startup	Búsqueda semántica: 35s → 125ms
Caché de metadatos	Publishers, themes, provincias y regiones se cachean 24h	Respuestas instantáneas en llamadas repetidas
Caché de municipios AEMET	Lista de municipios cacheada 24h	Evita rate limits en búsquedas por nombre
Paginación paralela	`fetch_all=True` descarga 5 páginas en paralelo	~5x más rápido
Descarga integrada	`get(id, include_data=true)` combina metadatos + datos	Una sola llamada
HTTP/2	Conexiones multiplexadas	Menor latencia en llamadas concurrentes
Retry con backoff	Reintentos automáticos (max 3) con backoff exponencial	Mayor resiliencia ante errores transitorios
Sinónimos INE	Expansión automática de consultas con sinónimos	Mejores resultados de búsqueda

Licencia

MIT License - ver LICENSE para más detalles.

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request en el repositorio.

Enlaces

Model Context Protocol - Especificación MCP
FastMCP - Framework para servidores MCP