io.github.cyanheads/imf-mcp-server

Official

by cyanheads · TypeScript

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

Query IMF macroeconomic data for 190 countries including WEO and exchange rates.

Topics

ai-agentsai-toolscyanheadseconomicsimfmcpmcp-servermodel-context-protocolsdmxstatisticstypescript

README.md13 KBView on GitHub

<div align="center"> <h1>@cyanheads/imf-mcp-server</h1> <p><b>Query IMF SDMX 3.0 macroeconomic data — 193 dataflows, 190 countries, WEO projections, BOP, CPI, exchange rates, and national accounts via MCP. STDIO or Streamable HTTP.</b> <div>5 Tools • 1 Resource</div> </p> </div> <div align="center">

</div> <div align="center">

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

</div>

Tools

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

Tool	Description
`imf_list_databases`	List all IMF SDMX dataflows available on the portal (193 total), with optional name/ID substring filtering
`imf_get_database`	Fetch a dataflow's dimension list and complete codelist — resolves human terms to SDMX codes before querying
`imf_query_dataset`	Query a dataflow by dimension key over a time range; large result sets spill to DataCanvas
`imf_dataframe_describe`	List DataCanvas tables and columns staged by a prior `imf_query_dataset` call
`imf_dataframe_query`	Run a read-only SQL SELECT across staged DataCanvas tables for multi-country comparisons and aggregations

`imf_list_databases`

Entry point for every IMF query workflow — browse and filter the full dataflow catalog.

193 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

`imf_get_database`

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

Returns all dimension IDs, positions, and their complete codelists (e.g. "United States" → USA, "real GDP growth" → 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
Codelists truncated at 50 entries inline; use codelist_filter to search large codelists by substring (returns all matches, uncapped), or the imf://database/{dataflow_id} resource for the full list

`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 real GDP growth)
+ syntax for multi-code positions (e.g. USA+GBR+DEU.NGDP_RPCH.A)
Returns observations with time_period, value, status, and series attributes (unit, scale, decimals)
Large multi-country or long time-range queries automatically spill to DataCanvas — canvas_id and table_name are returned for SQL follow-up
no_data errors include availability context from the upstream constraint endpoint: series_count=0 means the code has no coverage in the dataflow; series_count>0 means the combination is wrong and available_codes lists what does have data

`imf_dataframe_describe` / `imf_dataframe_query`

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

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

Call imf_query_dataset — if truncated: true, note the canvas_id and table_name
Call imf_dataframe_describe with the canvas_id to discover table schema
Call imf_dataframe_query with a SELECT statement for aggregations, cross-country comparisons, or time-series analysis

Only SELECT statements are accepted — DML and DDL are rejected. Requires CANVAS_PROVIDER_TYPE=duckdb.

Resource

Type	URI	Description
Resource	`imf://database/{dataflow_id}`	Full metadata for a single IMF SDMX dataflow — all dimensions with complete codelists, `key_format`, name, and description. Stable URI-addressable reference for known dataflow IDs (WEO, BOP, CPI, etc.).

All resource data is also reachable via imf_get_database. The resource URI provides the untruncated codelist for large dimensions that imf_get_database caps at 50 entries. The codelist_filter parameter on imf_get_database is a lighter alternative for targeted code lookup — it returns all substring matches without the cap.

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 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 spill is transparent — truncated, canvas_id, and table_name are always present in the output schema, letting callers branch on data rather than heuristics

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"
      ]
    }
  }
}

To enable SQL analytics over large result sets, add CANVAS_PROVIDER_TYPE=duckdb to the env block.

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

Clone the repository:

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

Navigate into the directory:

cd imf-mcp-server

Install dependencies:

bun install

Configure environment:

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

Configuration

Variable	Description	Default
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable DataCanvas spill for large result sets.	—
`IMF_BASE_URL`	IMF SDMX 3.0 base URL. Override for testing or proxied environments.	`https://api.imf.org/external/sdmx/3.0`
`IMF_REQUEST_TIMEOUT_MS`	Per-request timeout in milliseconds.	`30000`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

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

Path	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources and inits services.
`src/config/server-config.ts`	Server-specific env var parsing and validation with Zod.
`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.
`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

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.

Install

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "imf-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/imf-mcp-server@0.2.2",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Topics

Tools

imf_list_databases

imf_get_database

imf_query_dataset

imf_dataframe_describe / imf_dataframe_query

Resource

Data source

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

`imf_list_databases`

`imf_get_database`

`imf_query_dataset`

`imf_dataframe_describe` / `imf_dataframe_query`