oecd-mcp-server

---

概要

国民経済計算、雇用、貿易、教育、健康に関する 1,500 件以上のデータセットから OECD 統計を利用できます。データセットを検索し、ディメンションを確認し、観測値を照会して、複数の国にまたがる大規模な時系列データに SQL を実行できます。API キーは不要です。

ツール

5 つの検索・データツールと、大規模なクエリ結果を扱う 3 つの DataCanvas ツールを提供します。

ツール	説明
oecd_list_agencies	OECD SDMX 機関を一覧表示し、所管局と各機関が公開するデータフローの数を表示します
oecd_search_datasets	キーワードまたはテーマで 1,500 件以上の OECD データフローを検索します
oecd_get_dataset_info	データフローのディメンション、キーの順序、コードリストへの参照を取得します
oecd_get_dimension_values	1 つのディメンション（国、指標、頻度）の有効なコードとラベルを取得します
oecd_query_dataset	ディメンションキーと期間で絞り込んだ観測値を取得します。大きな結果は DataCanvas に出力されます
oecd_dataframe_describe	以前の oecd_query_dataset の出力によって DataCanvas に一時保存されたテーブルと列を一覧表示します
oecd_dataframe_query	DataCanvas テーブルに対して読み取り専用の SQL SELECT を実行します
oecd_dataframe_drop	分析完了後に一時保存された DataCanvas テーブルまたはビューを削除します。有効化するには OECD_DATAFRAME_DROP_ENABLED=true を設定します

リソース

リソース	説明
oecd://dataflow/{agency_id}/{flow_id}	単一の OECD データフローのディメンションメタデータ。oecd_get_dataset_info と同じ内容です

リソースのデータはすべてツールからも利用できます。同じ内容を取得するには oecd_get_dataset_info を使用してください。

機能リファレンス

oecd_list_agencies _ツール

• 入力はありません。すべての機関 ID（例：OECD.SDD.NAD）を、局名とデータフロー数とともに件数順で返します。
• 同じカタログを通じてデータフローを提供する OECD 以外の公開元（ESTAT、IAEG-SDGs）には局がありません。

---

oecd_search_datasets _ツール

• query はデータフロー名と説明をトークン照合します。任意の agency_id で対象を絞り込めます。limit（1～100）と offset でページ分割し、total_matches を返します。
• 各結果には、ほかのすべてのツールが受け取る識別子である flow_ref と、照合箇所（name、description、または both）を示す matched_in が含まれます。

---

oecd_get_dataset_info _ツール

• flow_ref を受け取ります。キー順にすべてのディメンションを返し、それぞれに概念名とコードリスト参照を含めます。また、oecd_query_dataset 用の key_example も返します。
• データフロー参照ではない文字列の場合は invalid_flow_ref、OECD が公開していないデータフローの場合は dataflow_not_found で失敗します。

---

oecd_get_dimension_values _ツール

• flow_ref と dimension_id を受け取ります。任意の query でコードとラベルの両方を部分文字列照合します。
• limit（1～500、既定値は50）と offset で一致結果をページ分割します。一致結果がさらにある場合は、全一致件数も返します。

---

oecd_query_dataset _ツール

• flow_ref と、ドット区切りの key（複数の値には + を使用し、空のセグメントはワイルドカードとして扱います）、任意の start_period／end_period を受け取ります。
• 観測値ごとに1行を返し、各ディメンションと属性をそれぞれ独立した列として含めます。value には value_scale が乗算されています。
• 結果が大きい場合は、truncated: true、canvas_id、table_name とともに DataCanvas に格納されます。canvas がない場合、すべての行は structuredContent に保持され、レンダリングされたテーブルのみが上限で制限されます（content_table_capped）。
• データが canvas に格納される場合は、canvas 名とテーブル名を示す notice が含まれます。列を確認するには oecd_dataframe_describe を使い、その後、結果全体に対する SQL には oecd_dataframe_query を使います。結果が収まる場合、新しい canvas は割り当てられません。明示的に canvas_id を指定した場合も検証されます。

---

oecd_dataframe_describe _ツール

• oecd_query_dataset が返した canvas_id を受け取ります。各ステージ済みテーブルとビューについて、行数、列名、列型を一覧表示します。

---

oecd_dataframe_query _ツール

• canvas_id と読み取り専用の SQL SELECT 文を1つ受け取ります。書き込み、DDL、システムカタログへのアクセスは拒否されます。
• canvas の行数上限まで行を返し、row_count で全件数を示します。

---

oecd_dataframe_drop _ツール

• canvas_id と、oecd_dataframe_describe に表示される table_name を受け取ります。削除したオブジェクトの kind と、残っている remaining_tables を返します。
• オプトイン方式です。一覧には表示されますが、OECD_DATAFRAME_DROP_ENABLED=true でない限り呼び出せません。

---

oecd://dataflow/{agency_id}/{flow_id} _リソース

• application/json として、oecd_get_dataset_info と同じ内容を返します。
• {flow_id} は {dsd_id}@{df_id} です。@ は %40 としてエンコードします（例：oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I）。または {df_id} のみを指定します。

特長

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

OECD 固有の機能：

• API キー不要でアクセス可能 — OECD SDMX 2.1 REST API は完全に公開されています
• OECD の 20 以上の統計部門にわたる 1,500 以上のデータフローを網羅しています（国民経済計算、雇用、インフレ、貿易、教育、医療、環境、課税、不平等）
• 委譲されたデータフローとコードリストの改訂をエンドツーエンドで解決します — OECD があるサービスルート上でカタログ化し、別のサービスルート上で定義しているデータフローでは、その構造、コード、観測値をカタログ自身のリンクから取得し、コードはエンドポイントの最新バージョンではなく、データ構造が指定する改訂版から取得します
• AllDimensions 観測モード — SDMX-JSON を 1 回の処理でフラットな行オブジェクトにデコードするため、ネストされた系列キーを再構築する必要はありません
• oecd_query_dataset は、大規模な観測値セット（複数国の時系列データ）を DuckDB DataCanvas に実体化し、会話内で SQL 分析できるようにします。3 つの oecd_dataframe_* ツールはこのデータを使用し、CANVAS_PROVIDER_TYPE=duckdb が必要です

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

• ワークフローを考慮したツール構成 — 検索で得た flow_ref を、再構築せずに情報、値、クエリの各ツールへそのまま渡せます
• スピル通知 — truncated: true と canvas_id により、エージェントは途中で切り詰められたインラインリストを解析するのではなく、SQL に切り替えるべきことがわかります
• SDMX のデコードをサーバー側ですべて実行 — エージェントには、生のインデックス配列ではなく、{ REF_AREA: "United States", MEASURE: "Gross domestic product", UNIT_MULT: "Billions", value: 26054614000000, value_scale: 1000000000 } が表示されます

はじめに

公開ホストインスタンス

公開インスタンスは https://oecd.caseyjhand.com/mcp で利用できます — インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

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

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "streamableHttp",
      "url": "https://oecd.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "oecd-mcp-server": {
      "url": "https://oecd.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、「設定」→「コネクタ」からリモートサーバーを追加します。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/oecd-mcp-server:latest"
      ]
    }
  }
}

大規模なクエリ結果に対する DataCanvas の SQL 分析は、デフォルトで有効です。無効にするには、CANVAS_PROVIDER_TYPE=none を追加します。

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "none"
      }
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーは不要です — OECD SDMX は無料の公開 API です。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/oecd-mcp-server.git

2. ディレクトリに移動します：

cd oecd-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env — most vars are optional; no API key required

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマによって検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
OECD_BASE_URL	OECD SDMX REST API のベース URL です。リダイレクトを追跡せず、直接応答する https オリジンである必要があります。そのため、平文の http:// オリジンは https にアップグレードされず、失敗します。	https://sdmx.oecd.org/public/rest
OECD_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）です。	30000
CANVAS_PROVIDER_TYPE	Canvas エンジンです。duckdb の場合、大きな oecd_query_dataset の結果は、レンダリングされたプレビューを上限で切り詰めるだけでなく、クエリ可能なテーブルに書き出されます。none の場合は、すべての行が引き続き structuredContent で返され、レンダリングされたテーブルのみが上限で切り詰められます。	duckdb
OECD_DATAFRAME_DROP_ENABLED	true に設定すると、oecd_dataframe_drop を登録します。無効の場合、このツールは無効として一覧表示され、クライアントは呼び出せません。	false
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションの方式です。stateful、stateless、または auto を指定します。ソースではサーバーが stateless と宣言されています。セッションごとの状態は保持せず、DataCanvas ハンドルは canvas_id をキーとするため、この値は上書きする場合にのみ設定してください。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名によるマスキングを行い、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）でサイズを制限します。自由形式の値に含まれるシークレットはマスキングされません。	false
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false

オプションの上書き設定の全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

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

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

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t oecd-mcp-server .
docker run --rm -p 3010:3010 oecd-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、および /var/log/oecd-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。
src/config/	Zod を使用した、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。OECD データの探索、取得、DataCanvas 分析を行う 8 つのツールがあります。
src/mcp-server/resources/definitions/	リソース定義（*.resource.ts）です。oecd://dataflow リソースがあります。
src/services/oecd-http/	OECD への共有フェッチ境界です。以下の 2 つのサービスで使用されるタイムアウトと再試行分類の修正、委譲先の各サービスルートがアクセスされる前に通過するオリジンチェック、設定されたホストからのリダイレクトの拒否、上流による拒否にすべてのツールとリソースで同じ宣言済みの理由を与える分類を担います。
src/services/oecd-structure/	OECD SDMX 構造サービスです。データフロー、データ構造、コードリストを扱います。
src/services/oecd-data/	OECD SDMX データサービスです。観測値、SDMX-JSON のデコード、DataCanvas への書き出しを扱います。
src/services/canvas-accessor/	DataCanvas アクセサーです。フレームワークの Canvas インスタンスをツールに登録して公開します。
tests/	src/ の構成を反映した単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使わないでください
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使ってください
• 新しいツールとリソースは、src/mcp-server/*/index.ts のバレル経由で登録してください
• 外部 API 呼び出しをラップしてください。生の SDMX-JSON を検証し、ドメイン型に正規化してから出力スキーマに従って返してください。不足しているフィールドを捏造してはいけません

コントリビューション

Issue を歓迎します。対応可能な Issue の条件については CONTRIBUTING.md を、協力の進め方については CODE_OF_CONDUCT.md をご覧ください。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE をご覧ください。