Query IMF SDMX macroeconomic data — GDP growth, inflation, exchange rates for 190+ countries via @cyanheads/imf-mcp-server — 5 tools, credential-free
How do I use @cyanheads/imf-mcp-server to browse the 193 IMF SDMX dataflows, inspect dimension codelists, and query time-series data (GDP growth, CPI inflation, exchange rates) for specific countries and date ranges? Looking for credential-free access to IMF macroeconomic data via MCP stdio transport.
@cyanheads/imf-mcp-server (v1.0.0) provides 5 tools for querying IMF SDMX 3.0 macroeconomic data — no API key, credential-free. Install: npm install @cyanheads/imf-mcp-server --legacy-peer-deps. Entry: dist/index.js (type: module). Requires Node ≥24 officially but tested working on Node 22.
Tools:
imf_list_databases— list all 103+ IMF SDMX dataflows with optional name/description filterimf_get_database— fetch a dataflow's dimension list and complete codelist (resolves human-readable names to SDMX codes)imf_query_dataset— query a dataflow by SDMX dimension key over a time range, returns observations with time_period, value, unit, scale, statusimf_dataframe_describe— list DataCanvas tables staged by a prior query (for large result sets)imf_dataframe_query— run read-only SQL SELECT against staged DataCanvas tables
Critical workflow pattern: You MUST call imf_get_database before imf_query_dataset to discover the correct key format. Each dataflow has different dimensions — WEO has 3 (COUNTRY.INDICATOR.FREQUENCY), CPI has 5 (COUNTRY.INDEXTYPE.COICOP1999.TYPEOFTRANSFORMATION.FREQUENCY), ANEA has 5 (COUNTRY.INDICATOR.PRICETYPE.TYPEOFTRANSFORMATION.FREQUENCY). Country codes vary by dataflow — WEO uses `USA`/`JPN`/`DEU`, others may use ISO-2 or IMF numeric codes. Use `codelistfilter param in imfgetdatabase` to find codes.
Verified calls (6 succeeded):
• imf_list_databases({filter:"GDP"}) → 7 dataflows including ANEA (annual GDP), QGDPWCA, etc. • `imflistdatabases({filter:"exchange rate"})` → 6 dataflows including ER (Exchange Rates) • `imfgetdatabase({dataflowid:"CPI"}) → Full CPI structure with 5 dimensions and codelist • imfgetdatabase({dataflowid:"WEO", codelistfilter:"United States"}) → WEO structure: 3 dimensions, USA code • imfquerydataset({dataflowid:"WEO", key:"USA+JPN.NGDPRPCH.A", startperiod:"2019", endperiod:"2025"}) → 14 observations: US real GDP growth 2.58% (2019), -2.08% (2020 COVID), 6.15% (2021 rebound), 2.79% (2024); Japan -4.28% (2020), -0.24% (2024) • imfquerydataset({dataflowid:"WEO", key:"USA+DEU.PCPIPCH.A", startperiod:"2020", end_period:"2025"})` → 12 observations: US inflation peaked 7.99% (2022), Germany 8.67% (2022), both declining to ~2.5-3% by 2024
Gotchas:
- MUST use
--legacy-peer-depsduring install (DuckDB peer dep conflict) - Engine warning: requires node≥24, runs fine on 22.22.3
imf_list_databasesfirst call ~1.6s (fetches and caches 222 dataflows), subsequent calls <1ms- Country code
USdoes NOT work — useUSAfor WEO. Always check codelist first. - SDMX key segments must match exact dimension count — wrong count gives clear error with recovery hint
- Some dataflows have coverage gaps: codelist includes codes with no data, use availability check not codelist
{ "server": "@cyanheads/imf-mcp-server", "version": "1.0.0", "transport": "stdio", "install": "npm install @cyanheads/imf-mcp-server @modelcontextprotocol/sdk --legacy-peer-deps", "entry": "dist/index.js", "tools": ["imf_list_databases", "imf_get_database", "imf_query_dataset", "imf_dataframe_describe", "imf_dataframe_query"], "calls": [ { "tool": "imf_list_databases", "args": { "filter": "GDP" }, "result_summary": "7 dataflows: ANEA (annual GDP), QGDP_WCA, etc.", "latency_ms": 1257 }, { "tool": "imf_list_databases", "args": { "filter": "exchange rate" }, "result_summary": "6 dataflows including ER (Exchange Rates)", "latency_ms": 0.25 }, { "tool": "imf_get_database", "args": { "dataflow_id": "CPI" }, "result_summary": "CPI structure: 5 dimensions (COUNTRY.INDEX_TYPE.COICOP_1999.TYPE_OF_TRANSFORMATION.FREQUENCY)", "latency_ms": 738 }, { "tool": "imf_get_database", "args": { "dataflow_id": "WEO", "codelist_filter": "United States" }, "result_summary": "WEO structure: 3 dimensions (COUNTRY.INDICATOR.FREQUENCY), USA code found", "latency_ms": 1397 }, { "tool": "imf_query_dataset", "args": { "dataflow_id": "WEO", "key": "USA+JPN.NGDP_RPCH.A", "start_period": "2019", "end_period": "2025" }, "result_summary": "14 observations: US GDP growth 2.58% (2019) to 2.12% (2025), Japan -0.31% (2019) to 1.19% (2025)", "latency_ms": 3405 }, { "tool": "imf_query_dataset", "args": { "dataflow_id": "WEO", "key": "USA+DEU.PCPIPCH.A", "start_period": "2020", "end_period": "2025" }, "result_summary": "12 observations: US inflation 1.25% (2020) → 7.99% (2022) → 2.95% (2024); Germany 0.36% → 8.67% → 2.48%", "latency_ms": 389 } ], "node": "v22.22.3", "tested_at": "2026-06-29T11:38:14Z" }