eurostat-mcp-server

---

概要

Eurostat の EU 統計データを提供します。対象は経済、人口統計、貿易、医療、NUTS 地域データのほか、詳細な Comext 貿易データや PRODCOM 工業生産データです。カタログを検索または閲覧し、データセットのディメンションを確認してから、一部を照会するか、データセット全体を一括ダウンロードできます。

ツール

3 つの eurostat_dataframe_* ツールには、既定で有効になっており、CANVAS_PROVIDER_TYPE=none で無効になるデータフレームキャンバスが必要です。eurostat_dataframe_drop には、さらに EUROSTAT_DATAFRAME_DROP_ENABLED=true が必要です。

ツール	説明
eurostat_search_datasets	キーワードで Eurostat のカタログを検索します。コード、説明、対象期間、テーマの階層を返します
eurostat_browse_themes	Eurostat のテーマ階層をたどります。ルートテーマの一覧表示や、サブテーマおよびデータセットへのドリルダウンができます
eurostat_get_dataset_info	データセットのメタデータを取得します。サンプル値付きの次元、期間、観測数、最終更新日を返します
eurostat_get_dimension_values	データセットの 1 つの次元について、有効なコードをすべてページ単位で一覧表示します。コード／ラベルの単語フィルターと、geo の NUTS 階層フィルタリングに対応しています
eurostat_query_dataset	次元フィルター、NUTS 地理レベル、期間指定を使って、デコード済みの観測データの上限付きプレビューを取得します
eurostat_download_dataset	SDMX 一括取得エンドポイントを介してデータセット全体をダウンロードし、すべての観測データをデータフレームキャンバスにステージングします
eurostat_dataframe_describe	データフレームキャンバスにステージングされたテーブルを、行数と列型とともに一覧表示します
eurostat_dataframe_query	ステージング済みテーブルを対象に、読み取り専用の SQL SELECT を実行します
eurostat_dataframe_drop	データフレームキャンバスから 1 つのステージング済みテーブルを削除し、ほかのテーブルはそのまま残します（オプトイン）

リソース

リソース	説明
eurostat://dataset/{dataset_code}	URI によるデータセットのメタデータ（次元、期間、観測数、最終更新日）
skill://eurostat-guide/SKILL.md	統計比較の判定基準、識別子の出典、SQL 分析ワークフロー

同じメタデータは、ツールのみを利用するクライアント向けに eurostat_get_dataset_info でも取得できます。

エージェントスキル

eurostat-guide では、国と地域の比較、Comext の集計、欠損データの解釈、ステージング済み観測データに対する SQL 結合について説明しています。プラグイン、npm、Docker、MCPB の各インストールに含まれており、MCP 経由で skill://eurostat-guide/SKILL.md として提供されます。補足の SQL 例は、スキルの references/ ディレクトリに含まれています。

機能リファレンス

eurostat_search_datasets _ツール

• query の単語は、各データセットのラベル、テーマの階層、コードを対象に、大文字と小文字を区別せず AND 検索されます。句読点の前後にある空白は無視されます（Rev.2 で Rev. 2 が見つかります）。limit は正の整数（既定値 20）で、通知とともに 100 に制限されます。次のページを取得するには、nextCursor を cursor として渡します。カーソルを指定した呼び出しでは limit は無視されます
• 結果には code、label、type（dataset / table）、対象期間、obsCount、lastUpdated、themePath が含まれ、すべてのページにわたる totalMatches も返されます。一致なし（削除すると一致が見つかる単語を示す no_match）、invalid_cursor、またはカタログが読み込まれておらず Eurostat の目次にアクセスできない場合の再試行可能な upstream_fault として失敗します
• Comext データフローの一覧を読み込めない場合、結果には comextListMissing と notice が含まれます。カタログを更新できなかった場合は catalogueLoadedAt が含まれます

---

eurostat_browse_themes _ツール

• トップレベルのテーマフォルダーを取得するには theme_code を省略します。フォルダーコードを渡すと、その直下の子項目が返されます。コードは完全一致を優先し、次に大文字と小文字を区別しない一致で解決されます。Comext コレクションは、詳細な貿易データが ext_go にある ext_go_detail と、icts にある prom（PRODCOM）の下にあります
• 項目には code、label、type（folder / dataset / table）、hasChildren が含まれます。また、階層を示す parentPath と、複数の分岐に登録されているフォルダーの otherPlacements も含まれます。不明なコードの場合は not_found、データセットまたはテーブルのコードの場合は not_a_folder、カタログが読み込まれておらず Eurostat の目次にアクセスできない場合は再試行可能な upstream_fault として失敗します
• Comext データフローの一覧を読み込めない場合、ext_go と icts には comextListMissing と notice が含まれます。カタログを更新できなかった場合は catalogueLoadedAt が含まれます

---

eurostat_get_dataset_info _ツール

• 1 つの dataset_code を指定します。各ディメンションの valuesCount と最大 10 件の sampleValues に加え、timeRange、obsCount、lastUpdated、ESMS の metadataUrl を返します
• 不明なデータセットの場合は not_found、Eurostat がサーバーで読み取れない構造を返した場合は upstream_fault で失敗します（エンドポイントがダウンしている場合は再試行可能です）

---

eurostat_get_dimension_values _ツール

• dataset_code と dimension を指定します。完全一致を優先し、次に大文字と小文字を区別せずに解決します（TIME_PERIOD は time の別名です）。返される値コードとラベルは変更されません。geo の場合、geo_level で NUTS レベルを選択します（デフォルトは aggregate、country、nuts1、nuts2、nuts3）。filter を指定すると、コードとラベルの両方に、指定したすべての単語を含む値を検索します。大文字と小文字、およびアクセント記号は区別されません（palma frankfurt で DE_EDDF_ES_LEPA が見つかります）。件数は matchCount に記録されます
• limit のデフォルトは 25 で、上限は 1,000 です。上限を超えた場合は通知されます。各ページには指定件数の値が含まれ、最終ページはそれより少なくなる場合があります。全リストの件数は totalCount に示されます。次のページがある場合は、truncated、nextCursor（cursor として渡します）、および notice が含まれます。続きのページでは有効な件数が引き継がれ、新しい limit は無視されます。1,000 を超える古いカーソルは 1,000 に正規化され、その旨が通知されます。not_found、no_results、conflicting_params、invalid_cursor、upstream_fault（エンドポイントがダウンしている場合は再試行可能）、または canvas_not_found で失敗します
• canvas_id を指定すると、そのキャンバス上にすべての値を code／label テーブルとしてステージングします（canvasId／tableName／stagedRowCount）。このテーブルを結合することで、ダウンロードのコード列にラベルを付与できます。このツールが独自にキャンバスを開始することはありません

---

eurostat_query_dataset _ツール

• dataset_code と filters（{dimension_code: [values]}）、geo_level、および since_period／until_period（2020、2020-Q1、2020-01、最小で YYYY-Wnn および YYYY-Dnnn）または last_n_periods のいずれかを指定します。preview_limit は正の整数で、デフォルトは 25、上限は 500 です。上限を超えた場合は通知されます。lang は EN、FR、または DE です
• stage: true を指定すると、サイズに関係なく、一致するデータ全体を利用可能なキャンバスにステージングします。canvas_id を再利用するか、省略すると新規作成します。指定しない場合、観測値が 5,000 件を超えると自動的にステージングが始まります。truncated は引き続きこのしきい値を示し、ステージングされた結果は tableName で識別できます。キャンバスが無効な環境では、明示的なステージング要求が利用不可であることが通知されます
• last_n_periods は、値が入力されたセルがない期間を含む、データセット上の時点の数を数えます。一致するデータ全体に含まれる期間の欠落を示す通知が表示されます（最新の 24 件まで。省略された件数も表示されます）。より古い観測値を取得するには、N を増やすか、until_period に置き換えてください
• 各観測値には、ディメンションごとのコード／ラベルのペア、null を許容する value、status（OBS_FLAG）、および confStatus（CONF_STATUS）が含まれます。obsCount、missingObsCount、および timeRange は一致するデータ全体を対象とします。観測値が 5,000 件を超えると truncated は true になり、フィルターに一致しなかった値は unmatchedValues に示されます
• not_found、no_results（一致しなかった値と、値のない期間を示します）、invalid_dimension、invalid_period、conflicting_params、提供できないほど大きなクエリに対する再試行不可の async_response、canvas_not_found、または Statistics API がダウンしている場合の再試行可能な upstream_fault で失敗します

---

eurostat_download_dataset _ツール

• dataset_codeに加えて、同じfiltersマップとsince_period／until_periodを指定します（last_n_periodsは指定できません。TSVでは、範囲によって除外されない限り、期間ごとに列が保持されるためです）。preview_limitは正の整数で、デフォルトは25です。500が上限で、上限を超えると通知が表示されます
• ダウンロード全体のrowCount（totalCountとして返されます）、missingCount、periodRange、bytesReadを返します。not_found、invalid_dimension、invalid_period、filter_arity、再試行できないasync_queuedまたはextraction_too_big、no_results、upstream_fault（SDMXエンドポイントが停止している場合は再試行可能）、またはcanvas_not_foundで失敗します
• EUROSTAT_BULK_MAX_BYTESの上限（デコード後のデフォルトは50 MiB）内で、許可された範囲に含まれる完全な観測値を保持し、budgetExceeded: trueを返します。完全なヘッダーと使用可能な観測値を収めるには上限が小さすぎる場合は、設定された上限と範囲を絞り込むための案内を含むbyte_budget_exceededで失敗します。bytesReadは受け入れられたデコード済みバイト数を示し、上限を超えることはありません。不完全な末尾の行は破棄されます。

---

eurostat_dataframe_describe _ツール

• ステージングの応答から取得したcanvas_idを指定します。各テーブルのname、rowCount、型付き列、expiresAt（スライディング方式のCANVAS_TTL_MS。デフォルトは24時間）を一覧表示します。canvas_not_foundまたはcanvas_disabledで失敗します
• 列はステージングツールによって異なります。eurostat_query_datasetは、ディメンションごとにコード列と_label列を書き込みます。eurostat_download_datasetはコード列のみとtimeを書き込みます（どちらもobs_*とconf_status*の指標を共有します）。eurostat_get_dimension_valuesはcodeとlabelを書き込みます

---

eurostat_dataframe_query _ツール

• 1回の呼び出しにつき、読み取り専用のSELECTを1つ実行します。連結されたステートメント、その他の動詞、ファイルや外部データを読み取る関数は拒否されます
• columns、rows、rowCount、必須のブール値truncatedを返します。キャンバスが提供する各行は、CANVAS_DEFAULT_ROW_LIMIT（デフォルトは10,000）まで、完全な状態で返されます。セルはネストや引用符付き文字列も含め、情報を損なわないJSONとして表示されます。64ビット整数は文字列として返されます。missing_table、canvas_not_found、またはcanvas_disabledで失敗します
• 結果が途中で切られた場合はtruncated: trueが設定され、通知が追加されます。変更されない決定的なSELECTに完全なORDER BY（同順位を解消する列も必要）、LIMIT、OFFSETを指定してページングし、実際のrowCount分だけオフセットを進めてください。最初に順序付けされていない結果のページングを再開する場合は、オフセット0から並べ替えてください。揮発性のSQLや変更・期限切れのテーブルでは、安定したページングを行えません

---

eurostat_dataframe_drop _ツール

• canvas_idとtable_nameを指定します。table_nameはeurostat_dataframe_describeに表示されたものと完全に一致する必要があります。指定したテーブルだけを削除し、キャンバスとほかのテーブルはそのまま残します。キャンバスと同じ場所でEUROSTAT_DATAFRAME_DROP_ENABLED=trueを設定した場合にのみ一覧に表示されます
• canvasId、tableName、dropped、expiresAtを返します。該当する名前のデータがステージングされていない場合、droppedはfalseとなり、通知が表示されます。そのため、削除を繰り返しても安全です。canvas_not_found、identifier_reserved、またはcanvas_disabledで失敗します

---

eurostat://dataset/{dataset_code} _リソース

• application/jsonとして返される、eurostat_get_dataset_infoと同じペイロードです。読み取りに失敗した場合も同じreasonが含まれ、サービス停止時にはretryableも含まれます
• dataset_codeはeurostat_search_datasetsまたはeurostat_browse_themesから取得します

特長

@cyanheads/mcp-ts-core をベースに構築されています。stdio と Streamable HTTP のトランスポート、プラグイン式の認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

Eurostat 固有の機能：

• スライス取得用の Statistics API（JSON-stat 2.0）、データセット全体を約半分のデータ量で取得できる SDMX 2.1 TSV 一括エンドポイント、12 時間メモリにキャッシュされるカタログ TOC
• Comext ホストの DS-* コレクション（CN8、HS、SITC、BEC、CPA 別の詳細な貿易データ、および PRODCOM）を同じツールで利用できます。貿易フローには年次と月次の系列が混在するため、freq を含むすべてのリクエストをフィルタリングしてください。TOTAL、EU27_2020、EXT_EU27_2020 などの集計値を構成要素と合算すると二重計上になります。PRODCOM のテキスト値は valueText / obs_value_text で返されます
• NUTS 地理レベルでのフィルタリング（aggregate / country / nuts1 / nuts2 / nuts3）に対応し、OBS_FLAG と CONF_STATUS は個別のフィールドにデコードされます
• 処理可能なサイズを超えるレスポンスは、再試行不可の async_response、extraction_too_big、または async_queued エラーとして返され、絞り込む必要があるディメンションが示されます
• stage: true を指定したクエリ、観測値が 5,000 件を超える検索、または一括ダウンロードは、DuckDB データフレームキャンバス上の SQL テーブル（canvasId / tableName / stagedRowCount）としてステージングされます。キャンバスはデフォルトで有効です。.mcpb バンドルではネイティブの DuckDB バインディングが除外され、CANVAS_PROVIDER_TYPE=none で実行されるため、SQL 分析には npm、Docker、またはソースからのインストールが必要です

エージェントに適した出力：

• 型付きエラーコントラクト：宣言されたすべての失敗に reason と、次に呼び出すツールを示す recovery.hint が含まれます
• 次のステップのヒント：eurostat_search_datasets と eurostat_browse_themes は、後続の呼び出し先を示す nextStep を返します
• 不明な値は不明のまま：Eurostat が報告しない件数と期間の境界（obsCount、timeRange.start / end、lastUpdated）は、ゼロに置き換えず省略されます
• 実際に適用されたクエリの通知：eurostat_query_dataset の appliedFilters と、eurostat_download_dataset の appliedQuery（SDMX の url を含む）を返し、プレビューで行が省略される場合は notice も返します

はじめに

ホストされたインスタンスに接続します：

claude mcp add --transport http eurostat-mcp-server https://eurostat.caseyjhand.com/mcp

またはローカルで実行します：

claude mcp add eurostat-mcp-server -- npx -y @cyanheads/eurostat-mcp-server

その他のクライアントでは、MCP 設定ファイルに以下を追加します：

{
  "mcpServers": {
    "eurostat-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/eurostat-mcp-server"]
    }
  }
}

API キーは不要です。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

変数	説明	デフォルト
EUROSTAT_BASE_URL	Eurostat API のベース URL。	https://ec.europa.eu/eurostat/api/dissemination
EUROSTAT_COMEXT_BASE_URL	すべての DS-* データセットコード（詳細な貿易統計と PRODCOM）を提供する Comext 配信ホスト。	https://ec.europa.eu/eurostat/api/comext/dissemination
EUROSTAT_REQUEST_TIMEOUT_MS	リトライ、バックオフ、本文の読み取りを含む、1 回のリクエストに対する合計許容時間（ミリ秒）。	30000
EUROSTAT_METADATA_TIMEOUT_MS	リトライ、バックオフ、本文の読み取りを含む、1 つのデータセットの SDMX データフロー構造に対する合計許容時間（ミリ秒）。	120000（2 分）
EUROSTAT_TOC_CACHE_TTL_MS	カタログ TOC キャッシュの有効期間（ミリ秒）。	43200000（12 時間）
EUROSTAT_BULK_TIMEOUT_MS	リクエストのリトライ、バックオフ、ストリーミングを含む、1 回の一括転送に対する合計許容時間（ミリ秒）。	120000（2 分）
EUROSTAT_BULK_MAX_BYTES	1 回の一括ダウンロードに対するバイト数の上限。	52428800（50 MiB）
CANVAS_PROVIDER_TYPE	データフレームキャンバスのバックエンドです。none にすると、キャンバスとそのツールが無効になります。.mcpb バンドルでは none が設定されます。	duckdb
CANVAS_TTL_MS	ステージングされたキャンバスのスライド式有効期間（ミリ秒）。	86400000（24 時間）
CANVAS_DEFAULT_ROW_LIMIT	eurostat_dataframe_query が truncated を報告する前に返す、完全な行の最大数。	10000
EUROSTAT_CLAMP_LIMITS	正の整数のプレビュー／検索／ディメンション上限を 500／100／1,000 に制限し、通知を表示します。false にすると、上限超過の入力を拒否するスキーマに戻ります。ゼロ、負の数、小数、数値以外の入力は常に拒否されます。各制限は一度だけログに記録され、ツールごとにラベル付けされた eurostat.limit_clamps がインクリメントされます。	true
EUROSTAT_DATAFRAME_DROP_ENABLED	true にすると eurostat_dataframe_drop が一覧に表示されます。CANVAS_PROVIDER_TYPE=none の場合は影響しません。	false
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。サーバーは stateless を宣言しますが、値が設定されている場合はその値が優先されます。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。Docker イメージでは info が設定されます。	debug
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果を、キー名に基づいて秘匿化し、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限としてログに記録します。自由形式の値に含まれるシークレットは秘匿化されません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

オプションのオーバーライドの全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以降（または Node.js v24 以降）が必要です。

git clone https://github.com/cyanheads/eurostat-mcp-server.git
cd eurostat-mcp-server && bun install
cp .env.example .env # optional; every setting has a default

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  bun run lint:mcp  # Validates MCP definitions against spec
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/eurostat-mcp-server:latest

イメージのデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/eurostat-mcp-server に出力されます。stdio を使用するには、docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/eurostat-mcp-server:latest を実行してください。ローカルでビルドするには docker build -t eurostat-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。データフレームツールはキャンバスの有効化を条件とし、ドロップツールは専用フラグで制御します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。6 つの探索・データツールに加え、キャンバスの有効化を条件とするデータフレームツールが 3 つあり、そのうち 1 つはオプトイン方式です。
src/mcp-server/resources	リソース定義です。データセットのメタデータリソースがあります。
src/services/eurostat-catalogue	カタログサービスです。Eurostat TOC を取得・解析し、Comext のデータフロー一覧と統合します。TTL で期限を管理するインメモリーキャッシュを備えています。
src/services/eurostat-data	統計 API サービスです。データセットごとのキャッシュを使った SDMX メタデータの解析、JSON-stat 2.0 のデコード、非同期レスポンスの検出、キャンバス行ソースを提供します。
src/services/eurostat-bulk	SDMX 2.1 TSV 一括取得サービスです。ストリーミングダウンロード、バイト予算、SOAP フォルトのマッピング、キャンバス行ソースを提供します。
src/services/eurostat-codelists.ts	OBS_FLAG と CONF_STATUS のコードリスト、両方のステージャーが書き込む指標列名、テキスト値のデコーダーです。
src/services/eurostat-hosts.ts	データセットコードを提供するホストを指定します。DS-* は Comext ホスト、それ以外はメインホストに割り当てます。
src/services/canvas-accessor.ts	オプションの DataCanvas 用アクセサーと、キャンバスにアクセスするツールが共有する acquire ヘルパーです。
src/services/shared-load.ts	同時に呼び出した複数の呼び出し元が 1 つのダウンロードを待機できるようにします。一方の呼び出し元がキャンセルしても、その呼び出し元だけが解放されます。
src/config	サーバー固有の環境変数を Zod で解析・検証します。
skills/	公開されている eurostat-guide と SQL リファレンスです。MCP 経由で提供され、インストールパッケージにも含まれます。
tests/	src/ の構成に対応するユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch は使いません。
• ログには ctx.log、ストレージには ctx.state を使用します。
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録します。
• 外部 API の呼び出しをラップする際は、生データを検証し、ドメイン型に正規化してから出力スキーマを返します。不足しているフィールドを捏造してはいけません。

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。