Open Data Spain MCP

MCP que unifica o acesso às principais fontes de dados abertos espanholas (BOE, INE, AEMET, Datos.gob.es)

Documentação

datos-gob-es-mcp

Hub de OpenData Espanhol - Servidor MCP (Model Context Protocol) que unifica o acesso às principais fontes de dados abertos da Espanha em uma única interface.

Descrição

Este servidor MCP atua como um hub centralizado que conecta múltiplas APIs de dados públicos espanhóis, permitindo que assistentes de IA como Claude, ChatGPT e outros clientes MCP acessem todas as informações a partir de um único ponto.

Fontes de dados integradas

Fonte	Descrição	Auth	Documentação
datos.gob.es	Catálogo nacional de dados abertos (+40.000 datasets)	Não	API
INE	Instituto Nacional de Estatística	Não	API
AEMET	Agência Estatal de Meteorologia	API key	API
BOE	Boletim Oficial do Estado	Não	API

Características

11 ferramentas MCP simplificadas para consultar múltiplas APIs de dados públicos
5 recursos MCP (templates dinâmicos) para acesso direto a dados
6 prompts MCP para guias de busca detalhadas
Busca semântica: Busca por significado usando embeddings (IA)
Cache de metadados: Cache local de 24h para respostas instantâneas
Paginação paralela: Download 5x mais rápido com fetch_all=True
Download integrado: get(id, include_data=true) em uma única chamada
Busca AEMET por nome: Usa nomes de município diretamente (ex: "Madrid")
Retry automático: Tentativas com backoff exponencial para maior resiliência
Sinônimos INE: Expansão de consultas para melhores resultados
Cliente HTTP assíncrono com rate limiting por API
Modelos Pydantic para tipagem segura
Pronto para implantar no FastMCP Cloud

Instalação

Requisitos

Python 3.10 ou superior
pip

Instalação 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

Instalação manual

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

# Instalar dependencias
pip install -r requirements.txt

Configuração

Variáveis de ambiente

Crie um arquivo .env com base em .env.example:

cp .env.example .env

Variável	Obrigatória	Descrição
`AEMET_API_KEY`	Para meteorologia	API key da AEMET OpenData (obter gratuitamente)
`PRELOAD_EMBEDDINGS_MODEL`	Não	Pré-carregar modelo de embeddings na inicialização (padrão: true)
`LOG_LEVEL`	Não	Nível de logging: DEBUG, INFO, WARNING, ERROR (padrão: INFO)
`LOG_FORMAT`	Não	Formato de logs: console ou json (padrão: console)
`RATE_LIMIT_DATOS_GOB_ES`	Não	Requisições/segundo para datos.gob.es (padrão: 10)
`RATE_LIMIT_INE`	Não	Requisições/segundo para INE (padrão: 5)
`RATE_LIMIT_AEMET`	Não	Requisições/segundo para AEMET (padrão: 10)
`RATE_LIMIT_BOE`	Não	Requisições/segundo para BOE (padrão: 10)

Uso

Executar o servidor MCP

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

# O directamente
mcp run server.py

Inspecionar ferramentas disponíveis

make inspect

Arquitetura

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

Capacidade	Quantidade	Descrição
Tools	11	Funções que o LLM pode invocar
Resources	5	Templates dinâmicos para acesso direto
Prompts	6	Guias de busca predefinidas

Tools (Ferramentas)

datos.gob.es (2 ferramentas)

Ferramenta	Descrição
`search`	Busca unificada de datasets: por filtros (título, tema, publicador, formato, data), semântica (IA com embeddings) ou híbrida. Suporta multi-tema com lógica OR e paginação paralela
`get`	Obtém metadados de um dataset e opcionalmente baixa seus dados. Com `include_data=true` baixa e parseia CSV/JSON (até 50MB)

INE - Instituto Nacional de Estatística (2 ferramentas) - FONTE PRINCIPAL DE ESTATÍSTICAS

O INE é a fonte oficial principal de estatísticas na Espanha. Contém dados de emprego (EPA), população, preços (IPC), PIB, turismo, censos e mais.

Ferramenta	Descrição
`ine_search`	Busca operações estatísticas ou lista tabelas. Use `query` para buscar operações, `operation_id` para listar tabelas
`ine_download`	Obtém dados estatísticos reais de uma tabela do INE

AEMET - Meteorologia (3 ferramentas)

Ferramenta	Descrição
`aemet_list_locations`	Lista municípios e/ou estações meteorológicas. Use `location_type` para filtrar
`aemet_get_observations`	Obtém observações meteorológicas atuais de uma estação
`aemet_get_forecast`	Obtém a previsão meteorológica para um município (aceita nome ou código)

BOE - Boletim Oficial do Estado (3 ferramentas)

Ferramenta	Descrição
`boe_get_summary`	Obtém o sumário do BOE. Se nenhuma data for especificada, retorna o BOE mais recente
`boe_get_document`	Obtém metadados completos de um documento do BOE por seu ID
`boe_search`	Busca documentos no BOE por texto em um intervalo de datas

Referência de IDs

Os IDs de temas, publicadores e províncias estão incluídos nas instruções do servidor MCP.

Temas (usar com `theme=`)

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

Principais publicadores (usar com `publisher=`)

ID	Organização
EA0010587	INE (Instituto Nacional de Estatística)
E05024401	Ministério da Fazenda
E05024301	Ministério da Economia
E00003901	AEMET
L01280796	Prefeitura de Madri
L01080193	Ajuntament de Barcelona

Resources (Recursos)

Templates dinâmicos para acesso direto a dados de datos.gob.es:

URI Template	Descrição	Exemplo
`dataset://{dataset_id}`	Informações de um dataset	`dataset://l01280066-presupuestos`
`theme://{theme_id}`	Datasets de uma temática	`theme://economia`
`publisher://{publisher_id}`	Datasets de um publicador	`publisher://E00003901`
`format://{format_id}`	Datasets em um formato	`format://csv`
`keyword://{keyword}`	Datasets com uma palavra-chave	`keyword://presupuestos`

Prompts (Guias de Busca)

Os prompts fornecem guias estruturadas para tarefas comuns de busca:

Prompt	Descrição
`buscar_datos_por_tema`	Busca guiada de datasets por temática e formato
`datasets_recientes`	Encontrar datasets atualizados nos últimos dias
`explorar_catalogo`	Exploração guiada do catálogo de dados abertos
`analisis_dataset`	Análise detalhada de um dataset específico
`guia_herramientas`	Documentação de todas as ferramentas MCP
`buscar_estadisticas`	Busca de estatísticas oficiais consultando INE e datos.gob.es

Exemplos 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últiplos temas

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

Obter e baixar dados em uma única chamada

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

Buscar estatísticas do 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

Obter o BOE mais recente

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")]

Obter previsão 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 aceita tanto nomes de municípios quanto códigos (ex: "28079" para Madri).

Configuração em Clientes MCP

Claude Desktop

Adicione ao seu arquivo de configuração claude_desktop_config.json:

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

Desenvolvimento

Comandos disponíveis

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

Estrutura do projeto

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

Desempenho

Latência por ferramenta

Tool	Latência Média	Classificação
`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

* Com PRELOAD_EMBEDDINGS_MODEL=true (habilitado por padrão). Ver relatório completo.

Otimizações implementadas

Melhoria	Descrição	Impacto
Pré-carga de embeddings	Modelo de ML é carregado na inicialização	Busca semântica: 35s → 125ms
Cache de metadados	Publishers, temas, províncias e regiões são armazenados em cache por 24h	Respostas instantâneas em chamadas repetidas
Cache de municípios AEMET	Lista de municípios armazenada em cache por 24h	Evita rate limits em buscas por nome
Paginação paralela	`fetch_all=True` baixa 5 páginas em paralelo	~5x mais rápido
Download integrado	`get(id, include_data=true)` combina metadados + dados	Uma única chamada
HTTP/2	Conexões multiplexadas	Menor latência em chamadas concorrentes
Retry com backoff	Tentativas automáticas (máx. 3) com backoff exponencial	Maior resiliência diante de erros transitórios
Sinônimos INE	Expansão automática de consultas com sinônimos	Melhores resultados de busca

Licença

MIT License - ver LICENSE para mais detalhes.

Contribuições

As contribuições são bem-vindas. Por favor, abra um issue ou pull request no repositório.