imf-mcp-server

Public Hosted Server: https://imf.caseyjhand.com/mcp

Tools

Six tools covering the full IMF SDMX 3.0 query workflow, plus a DuckDB-backed canvas layer for SQL analytics over large multi-country result sets:

imf_list_databases

Entry point for every IMF query workflow — browse and filter the dataflow catalog, a page at a time.

• Hundreds of dataflows covering WEO projections, balance of payments, CPI, exchange rates, money/finance statistics, and national accounts

• Vintage (historical snapshot) dataflows excluded by default; set include_vintages=true to include them

• Case-insensitive substring filter across ID, name, and description — matched against the full description, not the shortened one returned

• Paged: limit (default 50, max 200) and offset. total_count is the number of matches, returned_count the size of the page, and a notice names the next offset while matches remain

• Descriptions are cut to 200 characters here; imf_get_database and the imf://database/{dataflow_id} resource return the full text for the dataflow you settle on

imf_get_database

Resolve human-readable terms to SDMX dimension codes before querying.

• Returns every dimension ID, its position, its label from the DSD concept scheme (WGT_TYPE → Weight Type), and a codelist preview (e.g. "United States" → USA, "Constant prices" → NGDP_RPCH)

• Country codes are ISO 3-letter (USA, GBR, DEU — not US, GB, DE)

• key_format field shows the exact dot-separated dimension order required by imf_query_dataset

• Every codelist preview is bounded at 50 entries, including substring-filtered previews. Set dimension_id to page one codelist with limit/offset; codelist_filter still applies its case-insensitive substring match before paging

• Set available_only=true to replace codelists with codes reported by the dataflow-wide availability constraint. The response includes total series and time coverage, joins each available code to its DSD label with an ID fallback, and applies dimension_id, codelist_filter, limit, and offset after availability filtering. Omit dimension_id for a bounded preview of every structure dimension, including empty dimensions the constraint does not mention

• A filter that matches nothing is reported distinctly from a codelist that could not be resolved — the two need opposite next steps

imf_query_dataset

Query an IMF SDMX dataflow by dimension key over a time range.

• Dot-separated key in DSD keyPosition order (e.g. USA.NGDP_RPCH.A for WEO annual GDP at constant prices, percent change)

• + combines codes at one position (e.g. USA+GBR+DEU.NGDP_RPCH.A); * matches every code at a position (*.NGDP_RPCH.A for all countries, CAN.*.A for every indicator). Every position needs a code or a * — a blank segment matches nothing upstream and is rejected

• start_period / end_period accept YYYY, YYYY-SN, YYYY-QN, YYYY-MM, or a calendar-valid YYYY-MM-DD whatever the series frequency, and cover the whole period they name — end_period: 2023 includes 2023-M12 and 2023-Q4

• Returns observations with time_period, value, status, and series attributes (unit, scale, decimals). Period labels come back as upstream emits them — 2023, 2023-S1, 2023-Q1, 2023-M01, 2023-01-05 — and any of them can be passed straight back in as a bound

• A key resolving to several series carries series_metadata, one unit/scale/decimals entry per series_key, because attributes differ between them: in USA.NGDPD+NGDP_RPCH.*, NGDPD is USD at scale 9 while NGDP_RPCH is PT and unscaled. Canvas rows carry their own series' attributes too. A single-series query keeps the flat series_attributes and no list

• unit is the upstream code — PT, USD, XDC, IX, NUM. Every key shape reports the same unit: the portal drops the unit block when a key uses + on the dimension that carries it, and one extra attributes-only request recovers it, so USA.NGDP_RPCH+NGDPD.A and USA.NGDP_RPCH+NGDPD.* both report USD and PT. That key shape is the only one that costs the second request; every other query makes one. A unit: null therefore means the dataflow publishes none, which many do

• Scale 0 is the upstream sentinel for "no multiplier" — formatted output names it rather than printing a bare 0, and structuredContent keeps the raw code

• Large multi-country or long time-range queries automatically spill to DataCanvas; set output_mode: "canvas" to explicitly stage any result, using canvas_id as the destination when supplied

• staged reports whether the complete result is on DataCanvas; truncated reports only whether observations is an incomplete preview. Staged results always return canvas_id, table_name, and describe-before-query guidance in both MCP result channels

• no_data errors include availability context from the upstream constraint endpoint: a dataflow that publishes no series at all is reported as such and points at a different dataflow, since no key would work; otherwise series_count=0 means the code has no coverage and dataflow_availability names codes that do, while series_count>0 means the combination is wrong and available_codes lists what does have data per dimension, stating how many of how many it is showing when a dimension is too long to list in full

• A valid key whose data lies entirely outside the requested range fails as no_data_in_range, reporting the range the series actually spans — the fix is the range, not the key

imf_dataframe_describe / imf_dataframe_query / imf_dataframe_drop

In-conversation SQL analytics over the observation tables that imf_query_dataset stages on a DuckDB-backed canvas.

When imf_query_dataset returns staged: true, the full dataset is registered as a named table on the canvas. The workflow:

1. Call imf_query_dataset — let large results spill automatically or set output_mode: "canvas"; when staged: true, note the canvas_id and table_name

2. Call imf_dataframe_describe with the canvas_id to discover table schema

3. Call imf_dataframe_query with a SELECT statement for aggregations, cross-country comparisons, or time-series analysis

4. When table cleanup is enabled, call imf_dataframe_drop with a name from imf_dataframe_describe to remove only that table or view

One SELECT statement per call; a leading WITH … SELECT common table expression is accepted. DML and DDL are rejected. DataCanvas first caps materialization at its row limit (default 10,000), then the server retains the largest row prefix whose complete structured and formatted response fits 100,000 serialized characters. row_count always equals the returned rows; truncated: true means either cap omitted rows, and the remainder is reachable with a stable ORDER BY plus LIMIT/OFFSET. If one row cannot fit, response_too_large asks the caller to select fewer columns, aggregate, or shorten values. Requires CANVAS_PROVIDER_TYPE=duckdb.

imf_dataframe_drop is opt-in because it mutates the canvas. Set IMF_ENABLE_DATAFRAME_DROP=true to register it in tools/list; disabled HTTP deployments retain the exact enable hint in the HTML landing-page inventory. The SEP-1649 discovery document at /.well-known/mcp.json does not enumerate tool definitions. A successful removal returns dropped: true; an absent or previously removed name returns dropped: false while leaving the canvas and its other tables intact.

Related MCP server: cnbs-mcp-server

Resource

The resource stays bounded and points machine-readably to imf_get_database for continuation. To retrieve a large codelist, call imf_get_database with its dimension_id, then follow next_offset with limit/offset; add codelist_filter to page only entries whose ID or name contains a substring.

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

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

IMF SDMX-specific:

• Keyless access — no API key required; the IMF SDMX 3.0 portal is fully public

• Type-safe SDMX 3.0 compact JSON client with dimension/codelist parsing and DSD validation

• Key dimension count validated against the DSD before each query to catch format mismatches early

• Dataflow catalog and full availability constraints cached in-session to minimize round trips on multi-step workflows

• DuckDB-backed DataCanvas spill for large multi-country or long time-range observations

Agent-friendly output:

• Codelist entries carry both the machine code and human-readable label — agents can present meaningful names without a follow-up lookup

• key_format field in every dataflow response explicitly states the dimension order, removing guesswork for key construction

• Observations include status flags (e.g. E for estimate) so agents can communicate data quality caveats

• Canvas placement is explicit — staged distinguishes storage from truncated preview completeness, 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"
      ]
    }
  }
}

To enable SQL analytics over large result sets, add CANVAS_PROVIDER_TYPE=duckdb to the env block. 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.3.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

2. Navigate into the directory:

cd imf-mcp-server

3. Install dependencies:

bun install

4. 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:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

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

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

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.