eurostat-mcp

Eurostat のデータにアクセスするための MCP サーバー。ローカルモデル向けに設計 （Qwen3.8-27B でテスト済み）：ツールは 4 つ、スキーマは限定、サーバー側で 検証、出力はコンパクト。

アーキテクチャ

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)

モデルは SDMX URL を直接構築することはない。すべてのリクエストは query_data を経由し、キャッシュされた DSD に照らしてディメンションとコードを検証し、 対処可能なエラー（Code 'FRA' inconnu. Vouliez-vous : FR ?）を返す。

Related MCP server: DuckDB Eurostat MCP Server

インストール

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 クライアント設定（stdio）：

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

モデル側の典型的なフロー

1. search_datasets("GDP quarterly") → 候補コード

2. get_structure("namq_10_gdp") → ディメンション、切り詰めたコード

3. list_codes("namq_10_gdp", "geo", contains="fr") 必要に応じて

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

Qwen3.8-27B に関する注記：推論レベルは中または低めに固定すること（既定の xhigh は単純なツールの連携を考えすぎてしまう）。

完全オフラインモード

# 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

• データ：Parquet に zstd 圧縮された long 形式（dims, time, value, flag）、 データセットごとに 1 ファイル、DuckDB で照会される。query_data は オフラインモードでなくてもミラーを優先して提供し、データの日付 （"miroir local, données Eurostat du JJ.MM.AAAA"）を表示する。

• 構造＋カタログ：同期のたびに更新され、オフラインモードでは TTL なしで 提供される。Eurostat に接続できない場合は serve-stale-on-error。

• 無効化は TTL ではなく、TOC の last update of data 列によって制御される。 --resync は変更されたデータセットのみに作用する。

スケルトンの限界と今後の拡張

• 検索：FTS5/BM25 のみ。あいまいなクエリのため、エンベディング （例：sqlite-vec 内の bge-m3）を使ったハイブリッド検索を追加する。

• 構造：Statistics API の lastTimePeriod=1 という手法で取得する。 非常に大きなデータセットでは、専用パーサを伴う SDMX 2.1 の datastructure（XML）エンドポイントに移行する。

• データキャッシュ：キャッシュされるのは構造のみ。query数据 の応答5 キャッシュ（TTL 24 時間 — Eurostat は 11 時/23 時に公開）を追加する。

• 集計：store.py を DuckDB に移行し、モデルへ生データを返すのではなく、 サーバー側で集計（平均、成長率）を提供する。

• HTTP マルチユーザー：streamable HTTP トランスポートの前に、 認証（bearer）とレート制限を追加する。