Skip to main content
Glama
eurostat-mcp

eurostat-mcp

by scampion

eurostat-mcp

MCP server for accessing Eurostat data, designed for local models (tested for Qwen3.8-27B): 4 tools, narrow schemas, server-side validation, compacted outputs.

Architecture

Modèle (Qwen3.8-27B via vLLM / llama.cpp + harness MCP)
   │  tool calls
   ▼
server.py        4 tools : search_datasets, get_structure, list_codes, query_data
   │             validation DSD + suggestions difflib + plafond 400 cellules
   ▼
store.py         SQLite : catalogue en FTS5 (TTL 24h), structures DSD (TTL 24h)
   ▼
eurostat_client.py   API dissémination Eurostat (catalogue TSV + Statistics JSON-stat)

The model never builds SDMX URLs. Every request goes through query_data, which validates dimensions and codes against the cached DSD and returns actionable errors (Code 'FRA' unknown. Did you mean: FR ?).

Related MCP server: DuckDB Eurostat MCP Server

Installation

pip install "mcp>=1.2" httpx pyarrow duckdb   # SDK mcp 1.x et 2.x
python -m territorial_mcp.server                      # stdio
MCP_TRANSPORT=http python -m territorial_mcp.server   # streamable HTTP

MCP client config (stdio):

{
  "mcpServers": {
    "eurostat": {
      "command": "python",
      "args": ["-m", "territorial_mcp.server"],
      "cwd": "/chemin/vers/eurostat-mcp"
    }
  }
}

Typical model-side sequence

  1. search_datasets("GDP quarterly") → candidate codes

  2. get_structure("namq_10_gdp") → dimensions, truncated codes

  3. list_codes("namq_10_gdp", "geo", contains="fr") if needed

  4. query_data("namq_10_gdp", {"geo": "FR+BE", "na_item": "B1GQ", "unit": "CP_MEUR"}, time_from="2022")

Note for Qwen3.8-27B: force a medium/low reasoning level (the default xhigh over-thinks simple tool chains).

Full offline mode

# 1. (en ligne) construire le miroir — TOC-driven, idempotent
python -m territorial_mcp.mirror --datasets nama_10_gdp,une_rt_m
python -m territorial_mcp.mirror --all        # tout le catalogue, ~24 Go compressés
python -m territorial_mcp.mirror --resync     # cron quotidien : ne retélécharge
                                           # que ce que le TOC signale comme modifié

# 2. (hors ligne) servir uniquement depuis le miroir + caches
EUROSTAT_OFFLINE=1 python -m territorial_mcp.server
  • Data: Parquet zstd long format (dims, time, value, flag), one file per dataset, queried via DuckDB. query_data serves the mirror first even outside offline mode, and displays the data date ("local mirror, Eurostat data from DD.MM.YYYY").

  • Structures + catalog: updated at each sync, served without TTL in offline mode; serve-stale-on-error when Eurostat is unreachable.

  • Invalidation is driven by the last update of data columns of the TOC, not by a TTL: --resync only touches modified datasets.

Skeleton limits and future work

  • Search: FTS5/BM25 only. Add hybrid search with embeddings (e.g., bge-m3 in sqlite-vec) for vague queries.

  • Structures: retrieved via the lastTimePeriod=1 trick on the Statistics API. For very large datasets, switch to the SDMX 2.1 datastructure endpoint (XML) with dedicated parsing.

  • Data cache: only structures are cached. Add a cache for query_data responses (TTL 24h — Eurostat publishes at 11am/11pm).

  • Aggregations: migrate store.py to DuckDB to offer server-side aggregations (averages, growth) instead of returning raw data to the model.

  • Multi-user HTTP: add auth (bearer) and rate limiting in front of the streamable HTTP transport.

Available Tools

7 tools
get_indicatorsA

Valeurs d'indicateurs pour des zones, une colonne par indicateur.

Croise plusieurs sources en un seul tableau. Maximum 5 indicateurs et 100 zones ; sans time_from/time_to, les 3 dernières périodes. Les ids viennent de search_indicators, les codes de zone de list_zones.

Inputs: zones (required), indicators (required), time_to, time_from. Returns: result

get_structureA

Dimensions et codes d'un dataset (codelists tronquées).

À appeler avant query_data. Si une dimension affiche '… et N autres', utiliser list_codes pour la parcourir.

Inputs: dataset (required). Returns: result

list_codesA

Liste les codes d'une dimension, filtrable par sous-chaîne.

Exemple : list_codes("nama_10_gdp", "geo", contains="fr").

Inputs: dataset (required), dimension (required), contains. Returns: result

list_zonesA

Liste les zones d'un niveau NUTS0-3 ou CITY, sous un parent ou par nom.

Exemple : list_zones("NUTS2", parent="FR"). Les codes obtenus alimentent get_indicators.

Inputs: level (required), parent, contains. Returns: result

query_dataA

Interroge un dataset Eurostat au grain complet. filters = {dim: "A+B"}.

Exemple : query_data("nama_10_gdp", {"geo": "FR+BE", "na_item": "B1GQ", "unit": "CP_MEUR"}, time_from="2020"). Réponse plafonnée à 400 cellules. Pour croiser avec des indicateurs environnementaux ou d'infrastructure, préférer get_indicators.

Inputs: dataset (required), filters, time_to, time_from. Returns: result

search_datasetsA

Recherche full-text dans le catalogue Eurostat (~7000 datasets).

Renvoie code, titre et période couverte. Utiliser ensuite get_structure(code) avant toute requête de données.

Inputs: query (required), limit. Returns: result

search_indicatorsA

Cherche un indicateur (socio-économique, environnemental, infrastructure).

Point d'entrée de toute analyse territoriale croisée. source filtre sur eurostat, copernicus ou osm. Utiliser ensuite list_zones puis get_indicators.

Inputs: query (required), limit, source. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: search_indicators for finding indicators, list_zones for geographic zones, get_indicators for cross-source indicator values, search_datasets for dataset catalog search, get_structure for dataset dimensions, list_codes for browsing dimension codes, and query_data for raw dataset queries. No two tools overlap in function, and the descriptions explicitly guide the intended workflow.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern: search_indicators, list_zones, get_indicators, search_datasets, get_structure, list_codes, query_data. The verbs (search, list, get, query) and nouns are distinct and meaningful, with no mixed conventions or abbreviations.

    Tool Count5/5

    With 7 tools, the set is well-scoped for a Eurostat MCP server. It covers two clear workflows (indicator-based territorial analysis and raw dataset exploration) without excessive overlap or unnecessary additions. The count is ideal for the described functionality.

    Completeness5/5

    The tools cover the full lifecycle for both workflows: searching for indicators/datasets, exploring structure (zones, dimensions, codes), and retrieving data (indicators or raw queries). No obvious gaps exist; the separation between get_indicators and query_data is clearly explained, and helper tools (list_codes) fill potential needs.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers