Imf MCP Server

@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

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 time coverage; 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. Responses are held to 100,000 characters: with DataCanvas, larger results spill to it (output_mode: "canvas" forces staging, and staged reports storage); without it, 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, no_data, and no_data_in_range; a + key that partly returns lists the rest in missing_series. 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
• 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:

{

"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.

{

"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):

{

"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:

{

"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:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http

Server listens at http://localhost:3010/mcp

Prerequisites

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

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd imf-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env

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

Configuration

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

Running the server

Local development

• Build and run:

  bun run rebuild

bun run start:stdio

or

bun run start:http

• Run checks and tests:

`