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.