@cyanheads/imf-mcp-server

v0.1.4 pre-1.0

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.

public 5 tools 1 resources protocol 2025-11-25 github cyanheads/imf-mcp-server
@cyanheads/imf-mcp-server 
claude mcp add --transport http imf-mcp-server https://imf.caseyjhand.com/mcp
codex mcp add imf-mcp-server --url https://imf.caseyjhand.com/mcp
{
  "mcpServers": {
    "imf-mcp-server": {
      "url": "https://imf.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http imf-mcp-server https://imf.caseyjhand.com/mcp
{
  "mcpServers": {
    "imf-mcp-server": {
      "command": "bunx",
      "args": [
        "@cyanheads/imf-mcp-server@latest"
      ]
    }
  }
}
{
  "mcpServers": {
    "imf-mcp-server": {
      "type": "http",
      "url": "https://imf.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://imf.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'
Built on@cyanheads/mcp-ts-core v0.9.21

Tools

5

imf_list_databases

List all IMF SDMX dataflows available on the portal (193 total). 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.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "imf_list_databases",
    "arguments": {}
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "filter": {
      "description": "Optional name or ID substring to filter results. Case-insensitive. Example: \"exchange rate\" returns ER and related dataflows.",
      "type": "string"
    },
    "include_vintages": {
      "default": false,
      "description": "Include vintage (historical snapshot) dataflows such as WEO_2025_OCT_VINTAGE. Default false — vintages are excluded to keep the discovery surface clean.",
      "type": "boolean"
    }
  },
  "required": [
    "include_vintages"
  ],
  "additionalProperties": false
}
view source ↗

imf_get_database

Fetch a dataflow's dimension list and complete codelist for each dimension. Resolves human-readable terms to SDMX codes (e.g. "United States" → USA, "real GDP growth" → NGDP_RPCH). Required before imf_query_dataset — SDMX keys are opaque without codelist lookups. 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.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "imf_get_database",
    "arguments": {
      "dataflow_id": "<dataflow_id>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Case-sensitive."
    },
    "agency_id": {
      "description": "Agency ID that publishes this dataflow, e.g. IMF.RES or IMF.STA. Auto-detected from the dataflow list when omitted.",
      "type": "string"
    },
    "version": {
      "description": "Dataflow version, e.g. 9.0.0. Auto-detected from the dataflow list when omitted.",
      "type": "string"
    }
  },
  "required": [
    "dataflow_id"
  ],
  "additionalProperties": false
}
view source ↗

imf_query_dataset

open-world

Query an IMF SDMX dataflow by dimension key over a time range. Returns observations with time_period, value, unit, scale, and status attributes. 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). Use + to specify multiple codes per position (e.g. USA+GBR.NGDP_RPCH.A). Large analytical result sets (multi-country, long time range) spill to DataCanvas; imf_dataframe_query provides SQL analysis of spilled results.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "imf_query_dataset",
    "arguments": {
      "dataflow_id": "<dataflow_id>",
      "key": "<key>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dataflow_id": {
      "type": "string",
      "description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI."
    },
    "agency_id": {
      "description": "Agency ID, e.g. IMF.RES or IMF.STA. Auto-detected from dataflow list when omitted.",
      "type": "string"
    },
    "version": {
      "description": "Dataflow version. Auto-detected from dataflow list when omitted.",
      "type": "string"
    },
    "key": {
      "type": "string",
      "description": "Dot-separated dimension codes in DSD keyPosition order. Call imf_get_database to get key_format and valid codes first. Use + to specify multiple codes (e.g. USA+GBR.NGDP_RPCH.A). Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."
    },
    "start_period": {
      "description": "Requested start of time range. Format matches the dataflow frequency: YYYY (annual), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly). Note: the IMF SDMX 3.0 compact JSON endpoint returns the full available series regardless of this parameter — observations outside the requested range may still appear.",
      "type": "string"
    },
    "end_period": {
      "description": "Requested end of time range. Same format as start_period. See start_period note: the API returns the full series; this parameter is passed through but may not filter observations.",
      "type": "string"
    },
    "canvas_id": {
      "description": "Existing canvas ID to accumulate results into across multiple queries. Omit to allocate a fresh canvas; the response includes a canvas_id when results spill to DataCanvas.",
      "type": "string"
    }
  },
  "required": [
    "dataflow_id",
    "key"
  ],
  "additionalProperties": false
}
view source ↗

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.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "imf_dataframe_describe",
    "arguments": {
      "canvas_id": "<canvas_id>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "Canvas ID returned by imf_query_dataset when results were too large for inline delivery."
    }
  },
  "required": [
    "canvas_id"
  ],
  "additionalProperties": false
}
view source ↗

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. Only SELECT statements are accepted — DML and DDL are rejected.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "imf_dataframe_query",
    "arguments": {
      "canvas_id": "<canvas_id>",
      "sql": "<sql>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "Canvas ID returned by imf_query_dataset when results were too large for inline delivery."
    },
    "sql": {
      "type": "string",
      "description": "Read-only SQL SELECT statement. Must start with SELECT. Reference tables by the names returned by imf_dataframe_describe. Example: SELECT time_period, value FROM spilled_abc123 WHERE time_period >= '2010' ORDER BY time_period."
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "additionalProperties": false
}
view source ↗

Resources

1

imf-database

Metadata for a single IMF SDMX dataflow — dimensions with full codelists, key_format, name, and description. Stable URI-addressable reference for known dataflow IDs (WEO, BOP, CPI, etc.).

uri imf://database/{dataflow_id} mime application/json