Imf Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.6.0Updated Nov 12, 2026

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

VerifiedStreamable HTTPWeb executableFinanceData & Analytics

Overview

AI-generated overview

Queries IMF SDMX 3.0 macroeconomic dataflows — WEO, BOP, CPI, exchange rates and national accounts across 190 countries — with optional SQL over staged results.

What you can do
  • List and filter IMF dataflows, optionally including vintage snapshots
  • Fetch a dataflow's dimensions and codelist previews to resolve terms into SDMX codes
  • Query a dataflow by dimension key over a time range, returning observations with unit, scale and status
  • Describe and SQL-query large results staged in DataCanvas tables
  • Remove a staged table when the drop tool is enabled
  • Read per-dataflow discovery metadata as a resource
When to use it
Useful when an assistant needs official IMF macroeconomic figures — projections, balance of payments, CPI, exchange rates or national accounts — and should resolve country and indicator codes correctly, or run comparisons and aggregations over large multi-country result sets.
Requirements
Either the public hosted Streamable HTTP endpoint or a local process via npx/bunx (Bun 1.4.4+ or Node.js 24+) or Docker. No API key is required. Optional environment variables cover transport, HTTP host/port/path, log level, auth mode, DataCanvas provider, and the drop tool toggle. Network access to the IMF SDMX portal is needed.
Before you install
No credentials are requested, but the server sends queries to the public IMF portal and results must carry IMF attribution. DataCanvas is on by default, so large results are staged in local tables; the drop tool is disabled unless IMF_ENABLE_DATAFRAME_DROP is set, and enabling it lets the assistant delete staged tables. SQL is limited to read-only SELECT. The public hosted endpoint is a third-party instance, so consider self-hosting for sensitive use.

Installation

In SourceWeft

  1. Open Imf Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fimf-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

Source: README.md at commit 9957d71

Tools

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.

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

Parameterslimitoffsetversionagency_iddataflow_idrequireddimension_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

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

Parameterscanvas_idrequired

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.

Parameterssqlrequiredcanvas_idrequired

Version history

6
  1. v0.6.0LatestNov 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

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts