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 分