@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
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
Resources
Skill
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:
Self-Hosted / Local
No API key required. Add the following to your MCP client configuration file.
Or with npx (no Bun required):
Or with Docker:
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:
Prerequisites
- Bun v1.4.4 or higher (or Node.js v24+).
- No API key required.
Installation
- Clone the repository:
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
See .env.example for the full list of optional overrides.
Running the server
Local development
-
Build and run:
-
Run checks and tests:
Docker
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
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:
License
Apache-2.0 — see LICENSE for details.