Imf Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.6.0更新於 Nov 12, 2026

Query IMF SDMX 3.0 macroeconomic dataflows — WEO, BOP, CPI, exchange rates, 190 countries.

已驗證Streamable HTTP可網頁執行金融資料與分析

概覽

AI 產生的概覽

查詢 IMF SDMX 3.0 總體經濟資料流——WEO、國際收支、CPI、匯率與國民帳,涵蓋 190 個國家,並可對暫存結果執行 SQL。

可以做什麼
  • 列出並篩選 IMF 資料流,可選擇納入歷史版本快照
  • 取得資料流的維度與代碼表預覽,把自然語言詞彙解析為 SDMX 代碼
  • 依維度鍵與時間範圍查詢資料流,回傳觀測值及單位、量級與狀態
  • 檢視並以 SQL 查詢暫存在 DataCanvas 資料表中的大型結果
  • 在啟用刪除工具時移除某張暫存表
  • 以資源形式讀取單一資料流的探索中繼資料
適用情境
適合助手需要 IMF 官方總體經濟數據(預測、國際收支、CPI、匯率、國民帳),且須正確解析國家與指標代碼的情況;也適合對大型多國結果集做比較與彙總分析。
執行需求
可使用公開託管的 Streamable HTTP 端點,或透過 npx/bunx(需 Bun 1.4.4+ 或 Node.js 24+)或 Docker 在本機執行。不需要 API 金鑰。選用環境變數涵蓋傳輸方式、HTTP 主機/連接埠/路徑、日誌等級、驗證模式、DataCanvas 提供者以及刪除工具開關。需要能連線至 IMF SDMX 入口網路的網路。
安裝前請注意
不要求任何憑證,但查詢會送往公開的 IMF 入口網站,結果須保留 IMF 署名。DataCanvas 預設開啟,大型結果會暫存為本機資料表;刪除工具預設關閉,設定 IMF_ENABLE_DATAFRAME_DROP 後助手即可刪除暫存表。SQL 僅限唯讀 SELECT。公開託管端點為第三方實例,敏感用途建議自行部署。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Imf Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fimf-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@cyanheads/imf-mcp-server

Query IMF SDMX 3.0 macroeconomic data — 100+ dataflows across 190 countries, WEO projections, BOP, CPI, exchange rates, and national accounts via MCP. STDIO or Streamable HTTP.

6 Tools • 1 Resource • 1 Skill

Public Hosted Server: https://imf.caseyjhand.com/mcp


Overview

IMF macroeconomic data across 190 countries: World Economic Outlook projections, balance of payments, CPI, exchange rates, national accounts, and 100+ dataflows in all. Browse the catalog, resolve dimension codes, query time series, and run SQL over large multi-country results. No API key required.

Tools

ToolDescription
imf_list_databasesList IMF SDMX dataflows, with an optional word filter
imf_get_databaseFetch a dataflow's dimensions and codelists to resolve terms to SDMX codes
imf_query_datasetQuery a dataflow by dimension key over a time range
imf_dataframe_describeList DataCanvas tables and columns staged by imf_query_dataset
imf_dataframe_queryRun a read-only SQL SELECT across staged DataCanvas tables
imf_dataframe_dropRemove one staged table or view; disabled by default

Resources

ResourceDescription
imf://database/{dataflow_id}Discovery metadata for one dataflow: dimensions, codelist previews, and key_format

Skill

SkillDescription
imf-guideRouting a macro question to the dataflow that holds it, and reading results without mixing projections, group aggregates, or currency units. Served over MCP at skill://imf-guide/SKILL.md

Capability reference

imf_list_databases tool

  • filter keeps dataflows whose ID, name, or description contains every word (split on spaces and commas, case-insensitive); vintage snapshots such as WEO_2025_OCT_VINTAGE are excluded unless include_vintages=true
  • Paged with limit (default 50) and offset; a page holds at most 200, and a larger limit (up to 1,000) echoes requested_limit/applied_limit. total_count and returned_count report the match and page sizes
  • Descriptions are cut to 200 characters; imf_get_database returns the full text

imf_get_database tool

  • Resolves terms to SDMX dimension codes (countries are ISO 3-letter: USA, not US) and returns key_format, the dot-separated dimension order imf_query_dataset requires
  • Codelist previews hold 50 entries; set dimension_id to page one dimension with limit/offset (at most 200 per page, next_offset names the rest), and codelist_filter to keep codes whose ID or name contains every word
  • available_only=true pages only the codes the dataflow publishes, with series count and the first and last day with data (time_period_end is inclusive); agency_id/version are auto-detected when omitted

imf_query_dataset tool

  • Dot-separated key in DSD order, where + combines codes at a position and * matches all of them; codes and dataflow_id are case-insensitive. start_period/end_period accept YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or YYYY-MM-DD, and last_n_observations (1–1,000,000) keeps each series' last N observations
  • Returns time_period, value, status, and series attributes (unit, scale, decimals, reference_period where published), with one series_metadata entry per series. Inline responses are held to 100,000 characters: with DataCanvas, larger results spill to it (output_mode: "canvas" forces staging, and staged reports storage) and return the first 20 series' entries and up to 100 observations, with series_count and a SELECT DISTINCT query for the rest; without it, or at its canvas cap when an auto call omits canvas_id, the earliest observations return with truncated: true and retrieval_guidance
  • Key and range errors are invalid_key_code (with the nearest valid codes), wildcard_in_code_list, key_too_long, response_too_large (only on a result that was not staged), no_data, and no_data_in_range; a + key that partly returns lists the rest in missing_series. Canvas errors are canvas_not_found (an expired canvas_id: omit it to stage onto a fresh canvas) and canvas_capacity_exhausted (output_mode: "canvas" at the canvas cap, retryable). Upstream failures are data_unavailable and rate_limited, both retryable within a 45-second call budget

imf_dataframe_describe tool

  • Lists every staged table with row count and column names and DuckDB types as the engine spells them (DECIMAL(10,2), INTEGER[])
  • Requires canvas_id from an imf_query_dataset call that returned staged: true; call it before imf_dataframe_query
  • Not listed when CANVAS_PROVIDER_TYPE=none, like the other dataframe tools

imf_dataframe_query tool

  • One read-only SQL SELECT per call; a leading WITH … SELECT is accepted, DML and DDL are rejected
  • Results are capped by the canvas row limit (default 10,000), then a 100,000-character response budget; truncated: true means either cap trimmed the result. Page with a stable ORDER BY plus LIMIT/OFFSET
  • Oversized cells are clipped in the text table while structuredContent keeps every value; response_too_large means a single row exceeds the budget even so
  • Not listed when CANVAS_PROVIDER_TYPE=none

imf_dataframe_drop tool

  • Removes one named table or view from a canvas; requires the exact name from imf_dataframe_describe
  • A repeated or absent drop returns dropped: false rather than an error
  • Disabled by default; set IMF_ENABLE_DATAFRAME_DROP=true (DataCanvas must not be none) to register it

imf://database/{dataflow_id} resource

  • Every dimension with up to 50 codelist entries, plus counts, key_format, name, and description
  • dataflow_id comes from imf_list_databases; continuation metadata points to imf_get_database for codelists beyond the preview

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

IMF-specific:

  • Keyless access to the public IMF SDMX 3.0 portal
  • Typed SDMX 3.0 client that validates the key's dimension count against the DSD before each query
  • Dataflow catalog and availability constraints cached in-session
  • DuckDB-backed DataCanvas spill for large multi-country or long time-range results

Agent-friendly output:

  • Codelist entries carry both the machine code and the human-readable label
  • key_format in every dataflow response states the dimension order
  • Observations carry each dataflow's status flags (e.g. T, C, NA) for data-quality caveats
  • staged and truncated are reported separately, and staged results carry canvas_id, table_name, and retrieval guidance

Getting started

Public Hosted Instance

A public instance is available at https://imf.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

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

Self-Hosted / Local

No API key required. Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with Docker:

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

DataCanvas is on by default, so large result sets spill to tables the dataframe tools query with SQL; add CANVAS_PROVIDER_TYPE=none to the env block to turn it off. Add IMF_ENABLE_DATAFRAME_DROP=true only when agents should be able to remove staged tables.

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

  • Bun v1.4.4 or higher (or Node.js v24+).
  • No API key required.

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/imf-mcp-server.git
  1. Navigate into the directory:
sh
cd imf-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
cp .env.example .env# edit .env as needed — no required vars for basic use

Configuration

VariableDescriptionDefault
CANVAS_PROVIDER_TYPEDataCanvas spill and the dataframe tools. none disables both.duckdb
IMF_ENABLE_DATAFRAME_DROPRegister imf_dataframe_drop.false
IMF_BASE_URLIMF SDMX 3.0 base URL.https://api.imf.org/external/sdmx/3.0
IMF_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds (integer, 1–2147483647).30000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_SESSION_MODEHTTP session handling: stateful, stateless, or auto.stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false

See .env.example for the full list of optional overrides.

Running the server

Local development

  • Build and run:

    sh
    bun run rebuild
    bun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/imf-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources and inits services.
src/config/server-config.tsServer-specific env var parsing and validation with Zod.
src/config/canvas-default.tsDefaults CANVAS_PROVIDER_TYPE to duckdb; the entry point's first import.
src/mcp-server/tools/definitions/Tool definitions (*.tool.ts).
src/mcp-server/resources/definitions/Resource definitions (*.resource.ts).
src/services/canvas/DataCanvas accessor — wraps the framework canvas instance.
src/services/imf-sdmx/IMF SDMX 3.0 API client — dataflow catalog, DSD fetching, data queries.
skills/The published imf-guide agent skill, served over MCP and shipped to plugin installs and the .mcpb bundle.
tests/Unit and integration tests mirroring src/.
docs/Design notes and directory tree.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
  • Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Data source

Data is sourced from the International Monetary Fund SDMX 3.0 portal under the IMF Copyright and Terms of Use. The IMF's terms permit redistribution of statistical data with attribution. Each data-returning tool response includes a source field with the required attribution: Source: International Monetary Fund, <dataflow name>, https://data.imf.org/.

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 9957d71

工具

5

imf_list_databases

Imf List Databases

List IMF SDMX dataflows available on the portal. Entry point for every query: imf_get_database and imf_query_dataset both require a dataflow id obtained here. Vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE are excluded by default; set include_vintages=true to include them. Results are paged — 50 per call by default and at most 200, adjustable with limit and offset — and total_count reports how many dataflows matched. Descriptions are shortened here; imf_get_database returns the full text for a single dataflow.

輸入參數limitfilteroffsetinclude_vintages

imf_get_database

Imf Get Database

Fetch a dataflow's dimension list with a codelist preview for each dimension. Resolves human-readable terms to SDMX codes (e.g. "United States" → USA, "Constant prices" → NGDP_RPCH). Required before imf_query_dataset — SDMX keys are opaque without codelist lookups. Each codelist is capped at the first 50 entries by default, including previews filtered by codelist_filter. Set dimension_id to retrieve one codelist with bounded limit/offset paging after the optional codelist_filter, which keeps codes whose ID or name contains every word given. Set available_only=true to page codes the dataflow actually publishes, with series and time coverage metadata; availability filtering happens before codelist_filter and paging. The imf://database/{dataflow_id} resource provides the same bounded discovery summary. Country codes are ISO 3-letter (USA, GBR, DEU), not ISO 2-letter (US, GB, DE). The key_format field shows the exact dimension order required by imf_query_dataset. Note: codelists enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series in this dataflow.

輸入參數limitoffsetversionagency_iddataflow_id必填dimension_idavailable_onlycodelist_filter

imf_query_dataset

Imf Query Dataset

Query an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, and status, plus the unit, scale, and decimals of each series — a key resolving to several series carries one entry per series in series_metadata, since unit and scale differ between them. An index series also carries the reference_period it is based on (e.g. 2010A, 2010=100) exactly as published, on the series and, where the dataflow publishes one per observation, on each observation. Requires imf_get_database first to obtain the correct key_format and valid dimension codes. Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE). Key format: dot-separated codes in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO). Every position must carry a code: use + to combine codes (e.g. USA+GBR.NGDP_RPCH.A) and * to match every code at a position (e.g. *.NGDP_RPCH.A for all countries); * stands alone and cannot join a + list. Codes are matched case-insensitively and checked against each dimension's codelist before the query — an unknown code is rejected with the nearest valid codes. Codelists from imf_get_database enumerate the code universe, not actual coverage — valid codes can still return no_data if the combination has no series. When a + key returns data for some requested series and none for others, missing_series names each empty one with the reason a query for it alone gives (no_data or no_data_in_range). When the extra request that recovers the unit, scale, or decimals a + key suppresses fails, unresolved_attributes names them and how to get them. start_period and end_period must be valid period strings (YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD) with start_period no later than end_period; malformed or reversed ranges are rejected. A bound covers the whole period it names, so end_period 2023 includes 2023-M12 and 2023-Q4. last_n_observations keeps each series' last N observations — 1 is each series' latest value, the cheap way

輸入參數key必填versionagency_idcanvas_idend_perioddataflow_id必填output_modestart_periodlast_n_observations

imf_dataframe_describe

Imf Dataframe Describe

List DataCanvas tables and columns staged by a prior imf_query_dataset call. Returns each table's name, row count, and column schema (name + DuckDB type). Required before imf_dataframe_query to discover the table and column names for SQL.

輸入參數canvas_id必填

imf_dataframe_query

Imf Dataframe Query

Run a read-only SQL SELECT against a DataCanvas table staged by imf_query_dataset. Supports multi-country comparisons, time-series aggregation, and cross-indicator joins. Requires imf_dataframe_describe first to discover table and column names. One SELECT statement per call; a leading WITH … SELECT (CTE) is accepted. DML and DDL are rejected.

輸入參數sql必填canvas_id必填

版本歷史

6
  1. v0.6.0最新Nov 12, 2026
  2. v0.5.0Oct 29, 2026
  3. v0.4.4Oct 16, 2026
  4. v0.4.3Sep 30, 2026
  5. v0.4.2Sep 20, 2026
  6. v0.4.1Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分