imf-mcp-server

---

概要

190 か国にわたる IMF のマクロ経済データを利用できます。世界経済見通しの予測、国際収支、CPI、為替レート、国民経済計算、その他数百のデータセットを収録しています。カタログの閲覧、ディメンションコードの解決、時系列データの検索、大規模な複数国の結果に対する SQL の実行が可能です。API キーは不要です。

ツール

ツール	説明
imf_list_databases	IMF SDMX データフローの一覧を取得します。任意で単語による絞り込みができます
imf_get_database	データフローのディメンションとコードリストを取得し、用語を SDMX コードに対応付けます
imf_query_dataset	時間範囲を指定し、ディメンションキーでデータフローを検索します
imf_dataframe_describe	imf_query_dataset でステージングされた DataCanvas テーブルと列を一覧表示します
imf_dataframe_query	ステージングされた DataCanvas テーブル全体に対して、読み取り専用の SQL SELECT を実行します
imf_dataframe_drop	ステージングされたテーブルまたはビューを 1 つ削除します。デフォルトでは無効です

リソース

リソース	説明
imf://database/{dataflow_id}	1 つのデータフローの検出メタデータ：ディメンション、コードリストのプレビュー、key_format

機能リファレンス

imf_list_databases _ツール

• filter は、ID、名前、説明にスペースまたはカンマで分割したすべての単語が含まれるデータフローを対象にします（大文字と小文字は区別されません）。include_vintages=true でない限り、WEO_2025_OCT_VINTAGE などのビンテージスナップショットは除外されます
• limit（デフォルトは50）と offset を使ってページ分割されます。1ページあたり最大200件です。より大きな limit（最大1,000）を指定すると、requested_limit／applied_limit が返されます。total_count と returned_count は、それぞれ一致した件数とページ内の件数を示します
• 説明は200文字で切り詰められます。全文は imf_get_database で取得できます

---

imf_get_database _ツール

• 用語をSDMXディメンションコードに解決します（国はISO 3文字コードです。US ではなく USA を使用します）。imf_query_dataset が必要とする、ドット区切りのディメンション順序 key_format を返します
• コードリストのプレビューは50件です。dimension_id を指定すると、limit／offset で1つのディメンションをページ分割できます（1ページあたり最大200件で、残りは next_offset に示されます）。codelist_filter を指定すると、IDまたは名前にすべての単語が含まれるコードに絞り込めます
• available_only=true の場合、データフローで公開されているコードのみをページ分割して返し、系列数と期間のカバレッジも示します。省略された場合、agency_id／version は自動検出されます

---

imf_query_dataset _ツール

• DSDの順序に従ったドット区切りのキーです。各位置では + でコードを組み合わせ、* ですべてのコードに一致させます。コードと dataflow_id は大文字と小文字を区別しません。start_period／end_period には YYYY、YYYY-SN、YYYY-QN、YYYY-MM、または YYYY-MM-DD を指定でき、last_n_observations（1～1,000,000）を指定すると、各系列の直近N件の観測値が返されます
• time_period、value、status、系列属性（公開されている場合は unit、scale、decimals、reference_period）を返し、系列ごとに1件の series_metadata を含みます。応答は100,000文字に制限されます。DataCanvasを使用している場合、結果が大きいとDataCanvasに出力されます（output_mode: "canvas" を指定すると強制的にステージングされ、保存されたかどうかは staged に示されます）。DataCanvasを使用していない場合、最も古い観測値から返され、truncated: true と retrieval_guidance が付与されます
• キーおよび期間範囲のエラーは invalid_key_code（最も近い有効なコードを含む）、wildcard_in_code_list、key_too_long、response_too_large、no_data、no_data_in_range です。+ を含むキーで一部の系列のみが返された場合、残りは missing_series に列挙されます。上流の障害は data_unavailable と rate_limited で、どちらも45秒の呼び出し時間内であれば再試行できます

---

imf_dataframe_describe _ツール

• ステージングされたすべてのテーブルについて、行数、列名、DuckDBの型を一覧表示します
• staged: true を返した imf_query_dataset 呼び出しの canvas_id が必要です。imf_dataframe_query を呼び出す前に実行してください
• 他のデータフレームツールと同様に、CANVAS_PROVIDER_TYPE=duckdb の場合のみ一覧に表示されます

---

imf_dataframe_query _ツール

• 呼び出しごとに読み取り専用のSQL SELECT を1つ実行します。先頭が WITH … SELECT のクエリも使用できますが、DMLとDDLは拒否されます
• 結果はキャンバスの行数制限（デフォルトは10,000件）に続いて、100,000文字の応答上限で制限されます。どちらかの上限により結果が切り詰められた場合、truncated: true になります。安定した ORDER BY と LIMIT／OFFSET を使ってページ分割してください
• 大きすぎるセルはテキストテーブル内では切り詰められますが、structuredContent にはすべての値が保持されます。それでも1行が予算を超える場合は response_too_large になります
• CANVAS_PROVIDER_TYPE=duckdb の場合のみ一覧に表示されます

---

imf_dataframe_drop _ツール

• キャンバスから指定したテーブルまたはビューを1つ削除します。imf_dataframe_describe で確認できる正確な名前が必要です
• 同じ対象を再度削除した場合や、対象が存在しない場合は、エラーではなく dropped: false を返します
• デフォルトでは無効です。登録するには、CANVAS_PROVIDER_TYPE=duckdb とともに IMF_ENABLE_DATAFRAME_DROP=true を設定してください

---

imf://database/{dataflow_id} _リソース

• コードリストの項目が50件以下の各ディメンションに加え、件数、key_format、名前、説明を返します
• dataflow_id は imf_list_databases から取得します。プレビューを超えるコードリストについては、continuation メタデータが imf_get_database を案内します

機能

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

IMF 固有の機能：

• 公開 IMF SDMX 3.0 ポータルにキーなしでアクセスできます
• 型付けされた SDMX 3.0 クライアントが、各クエリの前にキーの次元数を DSD に照らして検証します
• データフローカタログと利用可能性制約をセッション内にキャッシュします
• 複数の国や長期間にわたる大量の結果を DataCanvas にスピルできるよう、DuckDB を使用します

エージェントが扱いやすい出力：

• コードリストのエントリには、機械処理用コードと人間が読めるラベルの両方が含まれます
• すべてのデータフローレスポンスの key_format に、次元の順序が示されます
• 観測値には、各データフローの status フラグ（例：T、C、NA）が含まれ、データ品質に関する注意事項を確認できます
• staged と truncated は個別に報告され、ステージングされた結果には canvas_id、table_name、取得方法の案内が含まれます

はじめに

公開ホストインスタンス

公開インスタンス https://imf.caseyjhand.com/mcp を利用できます。インストールは不要です。Streamable HTTP を使って、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "streamable-http",
      "url": "https://imf.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

API キーは不要です。以下を MCP クライアントの設定ファイルに追加してください。

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

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

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

または、Docker を使用します。

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

大量の結果に対する SQL 分析を有効にするには、env ブロックに CANVAS_PROVIDER_TYPE=duckdb を追加してください。ステージングされたテーブルをエージェントが削除できるようにする場合に限り、IMF_ENABLE_DATAFRAME_DROP=true を追加してください。

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 キーは不要です。

インストール

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

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

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

cd imf-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env as needed — no required vars for basic use

設定

変数	説明	デフォルト
CANVAS_PROVIDER_TYPE	DataCanvas へのスピルとデータフレームツールを有効にするには、duckdb に設定します。	—
IMF_ENABLE_DATAFRAME_DROP	imf_dataframe_drop を登録します。	false
IMF_BASE_URL	IMF SDMX 3.0 のベース URL です。	https://api.imf.org/external/sdmx/3.0
IMF_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）です。	30000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションの処理方法：stateful、stateless、または auto。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
OTEL_ENABLED	OpenTelemetry 計装を有効にします。	false

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

サーバーの実行

ローカル開発

• ビルドして実行：

  bun run rebuild
  
  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 imf-mcp-server .
docker run --rm -p 3010:3010 imf-mcp-server

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

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツール／リソースを登録し、サービスを初期化します。
src/config/server-config.ts	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。
src/mcp-server/resources/definitions/	リソース定義（*.resource.ts）です。
src/services/canvas/	DataCanvas アクセサーです。フレームワークの canvas インスタンスをラップします。
src/services/imf-sdmx/	IMF SDMX 3.0 API クライアントです。データフローカタログ、DSD の取得、データクエリを扱います。
tests/	src/ に対応する単体テストと統合テストです。
docs/	設計メモとディレクトリツリーです。

開発ガイド

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

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

データソース

データは国際通貨基金の SDMX 3.0 ポータルから、IMF の著作権および利用規約に基づいて取得しています。IMF の規約では、出典を明記することで統計データの再配布が認められています。データを返す各ツールのレスポンスには、必要な出典表記を含む source フィールドが含まれます。Source: International Monetary Fund, <dataflow name>, https://data.imf.org/。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。