imf-mcp-server
An MCP server that allows agents to query IMF SDMX 3.0 macroeconomic dataflows, including WEO projections, balance of payments, CPI, exchange rates, and national accounts for over 190 countries. It supports listing databases, resolving dimension codes, querying datasets, and running SQL on staged data.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://imf.caseyjhand.com/mcpWhat its tools do
5 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- List available IMF SDMX dataflows
- Resolve dimension codes to SDMX keys
- Query macroeconomic time series data
- Run SQL queries on staged data tables
Source and maintenance
Community listingRegistry 0.5.0
- Maintenance checked
Protocol and capabilities
- Server
- imf-mcp-server 0.5.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 5 advertised
- Resources
- 1 advertised
- Resource templates
- 2 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
5 advertised
imf_list_databases — Imf List Databases
Advertised read-onlyOpen-world
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.
imf_list_databases input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 1000,
"minimum": 1,
"description": "Maximum dataflows to return in this call. Default 50; one call returns at most 200, so a larger limit (up to 1,000) returns 200 and echoes requested_limit and applied_limit. total_count reports how many matched, so a partial page is always recognizable as one."
},
"filter": {
"type": "string",
"minLength": 1,
"description": "Optional words to filter results by, split on spaces and commas. A dataflow matches when every word appears, case-insensitively, somewhere in its ID, name, or full description. Example: \"exchange rate\" returns ER and related dataflows; \"WEO outlook\" returns WEO and the regional outlooks built on it."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of matching dataflows to skip before this page. Combine with limit to page through a broad or unfiltered catalog."
},
"include_vintages": {
"type": "boolean",
"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."
}
},
"additionalProperties": false
}imf_list_databases output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflows",
"total_count",
"returned_count",
"offset"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit that bounded this page."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"dataflow_list_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `dataflow_list_unavailable`: The IMF SDMX structure endpoint that backs the dataflow catalog did not return a usable response. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Dataflows returned in this page."
},
"notice": {
"type": "string",
"description": "Populated when the filter matches nothing, or when matches remain beyond this page — explains why and names the next offset to request."
},
"offset": {
"type": "number",
"description": "Number of matching dataflows skipped before this page."
},
"dataflows": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"agency_id",
"version",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Dataflow identifier, e.g. WEO, BOP, CPI."
},
"name": {
"type": "string",
"description": "Human-readable dataflow name."
},
"version": {
"type": "string",
"description": "Dataflow version, e.g. 9.0.0."
},
"agency_id": {
"type": "string",
"description": "Agency that publishes this dataflow, e.g. IMF.RES."
},
"description": {
"type": "string",
"description": "Short description, cut to 200 characters and ended with … when longer. imf_get_database and the imf://database/{dataflow_id} resource return the full text."
}
},
"description": "A single IMF SDMX dataflow entry.",
"additionalProperties": false
},
"description": "This page of matching dataflows; pass the id to imf_get_database to resolve dimension codelists."
},
"truncated": {
"type": "boolean",
"description": "True when matching dataflows remain beyond this page."
},
"total_count": {
"type": "number",
"description": "Dataflows matching filter and include_vintages, before limit and offset are applied. Exceeds returned_count when more pages remain."
},
"applied_limit": {
"type": "number",
"description": "The limit this page was cut to — the per-call maximum of 200 — echoed beside requested_limit."
},
"returned_count": {
"type": "number",
"description": "Dataflows in this page — the length of dataflows."
},
"requested_limit": {
"type": "number",
"description": "The limit requested, echoed only when it exceeded the per-call maximum of 200."
}
},
"additionalProperties": false
}imf_list_databases annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}imf_get_database — Imf Get Database
Advertised read-onlyOpen-world
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.
imf_get_database input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"dataflow_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50000,
"minimum": 1,
"description": "Entries to return from the selected dimension. Valid only with dimension_id; default 50. One call returns at most 200, so a larger limit (up to 50,000) returns 200, echoes requested_limit and applied_limit, and next_offset names the rest."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Matching entries to skip in the selected dimension before this page. Valid only with dimension_id; default 0."
},
"version": {
"type": "string",
"description": "Dataflow version, e.g. 9.0.0. Auto-detected from the dataflow list when omitted."
},
"agency_id": {
"type": "string",
"description": "Agency ID that publishes this dataflow, e.g. IMF.RES or IMF.STA, matched case-insensitively. Auto-detected from the dataflow list when omitted."
},
"dataflow_id": {
"type": "string",
"description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI."
},
"dimension_id": {
"type": "string",
"minLength": 1,
"description": "Exact dimension ID from this tool, e.g. INDICATOR. Select one dimension to page beyond its preview."
},
"available_only": {
"type": "boolean",
"default": false,
"description": "Return only codes reported by the dataflow-wide availability constraint. Default false keeps ordinary codelist discovery unchanged."
},
"codelist_filter": {
"type": "string",
"minLength": 1,
"description": "Optional words to search for in each dimension's codelist, split on spaces and commas. A code matches when every word appears, case-insensitively, in its code ID or name; different words may match different fields. Filtering runs before the 50-entry preview or selected-dimension page. Example: \"CPI\", \"GDP constant prices\", or \"NGDP_RPCH percent\" surfaces matching WEO indicator codes."
}
},
"additionalProperties": false
}imf_get_database output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflow_id",
"agency_id",
"version",
"name",
"key_format",
"truncated",
"dimensions",
"source"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"name": {
"type": "string",
"description": "Human-readable dataflow name."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"dataflow_not_found",
"dimension_not_found",
"structure_unavailable",
"dataflow_list_unavailable",
"availability_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id matches no catalog dataflow on api.imf.org, or none under the agency_id and version given. `dimension_not_found`: dimension_id does not match a dimension in the selected dataflow. `structure_unavailable`: api.imf.org returns non-200 on the DSD endpoint. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD lookup is attempted. `availability_unavailable`: available_only is true and the dataflow-wide availability constraint cannot be fetched or parsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Populated when a codelist_filter matched no entries anywhere, or when a dimension has no resolvable codelist, or when offset is past the final match."
},
"source": {
"type": "string",
"description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\"."
},
"version": {
"type": "string",
"description": "Dataflow version string, e.g. 9.0.0."
},
"agency_id": {
"type": "string",
"description": "Agency that publishes this dataflow, e.g. IMF.RES, IMF.STA."
},
"truncated": {
"type": "boolean",
"description": "True when any returned dimension page omits matching codes."
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"position",
"codelist",
"codelist_truncated",
"unfiltered_count",
"matched_count",
"returned_count",
"offset"
],
"properties": {
"id": {
"type": "string",
"description": "Dimension identifier used in the key, e.g. COUNTRY."
},
"name": {
"type": "string",
"description": "Human-readable dimension label from the DSD concept scheme, e.g. Weight Type for WGT_TYPE. Falls back to the dimension id when the structure names no concept."
},
"offset": {
"type": "number",
"description": "Matching codes skipped before this dimension page."
},
"codelist": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Machine code for this dimension value, e.g. USA."
},
"name": {
"type": "string",
"description": "Human-readable label for this value, e.g. United States."
}
},
"description": "A single codelist entry: machine code and human-readable name.",
"additionalProperties": false
},
"description": "Valid codelist codes for this dimension, or codes reported with published data when available_only is true. Unselected previews show up to 50 entries after optional filtering. Select dimension_id and use limit/offset for a bounded page of up to 200 entries. Empty means the filter matched nothing when codelist_filter is echoed back, no coverage was reported in availability mode, or the codelist could not be resolved in normal mode — see notice."
},
"position": {
"type": "number",
"description": "Zero-based position in the key string."
},
"next_offset": {
"type": "number",
"description": "Offset for the next page when later matching codes remain."
},
"matched_count": {
"type": "number",
"description": "Codes matching codelist_filter before limit and offset are applied."
},
"returned_count": {
"type": "number",
"description": "Codes returned in this dimension page."
},
"available_count": {
"type": "number",
"description": "Codes reported with published data before codelist_filter. Present when available_only is true."
},
"unfiltered_count": {
"type": "number",
"description": "Source codes before codelist_filter: the complete resolved codelist normally, or published codes when available_only is true."
},
"codelist_truncated": {
"type": "boolean",
"description": "True when matching codes were omitted before or after this page."
}
},
"description": "A single dimension with its codelist or published availability coverage.",
"additionalProperties": false
},
"description": "All dimension previews, or the one selected dimension page."
},
"key_format": {
"type": "string",
"description": "Dimension names in dot-separated keyPosition order, e.g. COUNTRY.INDICATOR.FREQUENCY. Use this exact format when constructing the key for imf_query_dataset."
},
"dataflow_id": {
"type": "string",
"description": "Dataflow identifier, e.g. WEO, BOP, CPI."
},
"description": {
"type": "string",
"description": "This dataflow's own description in full — not the shared DSD's, and not the shortened preview imf_list_databases returns for the same id. Absent when the dataflow publishes none."
},
"dsd_version": {
"type": "string",
"description": "Version of the underlying data structure definition (DSD) that backs this dataflow. Differs from version when the dataflow references a shared DSD (e.g. IIP → DSD_BOP at 24.0.0)."
},
"dimension_id": {
"type": "string",
"description": "Selected dimension ID. Absent when previews for every dimension were returned."
},
"series_count": {
"type": "number",
"description": "Total series published by the dataflow. Present when available_only is true."
},
"applied_limit": {
"type": "number",
"description": "The limit the selected dimension's page was cut to — the per-call maximum of 200 — echoed beside requested_limit."
},
"structure_ref": {
"type": "string",
"description": "Identifier of the underlying DSD, e.g. DSD_BOP. Several dataflows can share one DSD."
},
"available_only": {
"type": "boolean",
"const": true,
"description": "True when dimensions contain published availability coverage rather than codelists."
},
"codelist_filter": {
"type": "string",
"description": "Echo of the codelist_filter that produced this result. Absent when no filter was applied — an empty codelist then means the codelist could not be resolved, not that the filter missed."
},
"requested_limit": {
"type": "number",
"description": "The limit requested, echoed only when it exceeded the per-call maximum of 200."
},
"time_period_end": {
"type": [
"string",
"null"
],
"description": "Latest period with published data, or null when the constraint omits it."
},
"time_period_start": {
"type": [
"string",
"null"
],
"description": "Earliest period with published data, or null when the constraint omits it."
}
},
"additionalProperties": false
}imf_get_database annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}imf_query_dataset — Imf Query Dataset
Advertised read-onlyOpen-world
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 to ask many countries for their latest figure. Values are in base units everywhere, staged canvas rows included: scale is the power of ten the IMF publishes a series in (value / 10^scale is the published figure), never a factor still to apply. A response is held to 100,000 serialized characters. With DataCanvas enabled (CANVAS_PROVIDER_TYPE=duckdb), a larger result (multi-country, long time range) spills to it: call imf_dataframe_describe first to inspect staged tables and columns, then imf_dataframe_query for SQL analysis. Without DataCanvas, a larger result returns its earliest observations with truncated=true, and retrieval_guidance names the last period returned and how to narrow the query.
imf_query_dataset input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"dataflow_id",
"key"
],
"properties": {
"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 combine codes at one position (e.g. USA+GBR.NGDP_RPCH.A). Use * to match every code at a position — *.NGDP_RPCH.A returns the indicator for all countries, and CAN.*.A every indicator for Canada. Every position needs a code or a *; an empty segment (USA..A) is rejected. A * stands alone at its position — combined with other codes (USA+*) it is rejected. Codes are trimmed and matched case-insensitively (usa resolves to USA), empty and repeated + members are dropped (USA++GBR+USA is queried as USA+GBR, and notice says so), and the response echoes the canonical key. A code missing from its dimension's codelist is rejected before the query, naming the nearest valid codes. The portal limits the request URL, so a + list of a few hundred codes is rejected as too long — use * there, or split the codes across calls. Country codes are ISO 3-letter: USA not US, GBR not GB, DEU not DE."
},
"version": {
"type": "string",
"description": "Dataflow version, e.g. 9.0.0. Auto-detected from dataflow list when omitted."
},
"agency_id": {
"type": "string",
"description": "Agency ID, e.g. IMF.RES or IMF.STA, matched case-insensitively. Auto-detected from dataflow list when omitted."
},
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Existing canvas ID to accumulate results into across multiple queries. This selects the destination only; it does not force staging. Use output_mode=\"canvas\" to stage an under-budget result."
},
"end_period": {
"type": "string",
"description": "End of time range (inclusive). Same formats as start_period, and must not be earlier than it. The bound covers the whole period it names, so end_period 2023 admits 2023-M12 and 2023-Q4. Observations after this period are excluded from the result."
},
"dataflow_id": {
"type": "string",
"description": "Dataflow identifier from imf_list_databases, e.g. WEO, BOP, CPI. Matched case-insensitively; the response echoes the catalog spelling."
},
"output_mode": {
"enum": [
"auto",
"canvas"
],
"type": "string",
"default": "auto",
"description": "Result placement. auto returns an under-budget result inline and spills only when needed. canvas explicitly stages the full result, using canvas_id when supplied or allocating a fresh canvas."
},
"start_period": {
"type": "string",
"description": "Start of time range (inclusive). Accepts any of YYYY (annual), YYYY-SN (semi-annual, e.g. 2023-S1), YYYY-QN (quarterly, e.g. 2023-Q1), YYYY-MM (monthly), or a calendar-valid YYYY-MM-DD (daily), whatever the dataflow's frequency. The bound covers the whole period it names, so start_period 2023 admits 2023-M01 and 2023-Q1. Observations before this period are excluded from the result."
},
"last_n_observations": {
"type": "integer",
"maximum": 1000000,
"minimum": 1,
"description": "Keep only each series' last N observations, an integer from 1 to 1,000,000; 1 returns each series' latest value. Latest is per series: series end at different periods, and a WEO series ends in its projection years (e.g. 2031), so set end_period to stop at a past year. With start_period or end_period, the last N inside that range. A series with fewer than N observations is returned whole. Omit to return every observation."
}
},
"additionalProperties": false
}imf_query_dataset output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataflow_id",
"key",
"observations",
"series_attributes",
"observation_count",
"staged",
"truncated",
"source"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"key": {
"type": "string",
"description": "Dimension key used in the query, trimmed and with each code in its codelist spelling, e.g. USA.NGDP_RPCH.A."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"dataflow_not_found",
"no_data",
"no_data_in_range",
"key_dimension_mismatch",
"empty_key_segment",
"wildcard_in_code_list",
"invalid_key_code",
"key_too_long",
"invalid_period_format",
"invalid_period_range",
"structure_unavailable",
"canvas_unavailable",
"response_too_large",
"dataflow_list_unavailable",
"data_unavailable",
"rate_limited"
],
"description": "Machine-readable failure mode. Declared by this tool: `dataflow_not_found`: dataflow_id matches no catalog dataflow on api.imf.org, or none under the agency_id and version given. `no_data`: Key is structurally valid but the dataflow holds no series for this code combination, or the dataflow publishes no series at all. `no_data_in_range`: The key returned observations but start_period/end_period excluded every one of them. `key_dimension_mismatch`: Number of dot-separated segments in key does not match the dataflow's DSD dimension count. `empty_key_segment`: A dot-separated position in key is empty or blank, or holds only empty + members (USA.NGDP_RPCH.+), which matches no series upstream. `wildcard_in_code_list`: A key position combines * with other codes in a + list, where the portal ignores the * and returns only the listed codes. `invalid_key_code`: A key code is not in its dimension's codelist, checked before any data request. `key_too_long`: The IMF portal refused the data request because its URL is too long — a + list of a few hundred codes at one position. `invalid_period_format`: start_period or end_period is not one of the recognized period formats. `invalid_period_range`: start_period is later than end_period. `structure_unavailable`: The dataflow structure (DSD) cannot be fetched after the dataflow catalog resolved successfully. `canvas_unavailable`: output_mode=\"canvas\" was requested but DataCanvas is disabled. `response_too_large`: The fixed part of the result — full series_metadata, plus the retrieval handle when staging — exceeds the response budget before any observation can be included. `dataflow_list_unavailable`: The dataflow catalog that dataflow_id is resolved against could not be fetched — fires before the DSD and data lookups are attempted. `data_unavailable`: The data request failed after its retries — the portal answered 5xx or an unusable body, could not be reached, or timed out — or the call spent its 45-second budget for upstream requests. `rate_limited`: The IMF portal answered the data request with HTTP 429 after its retries. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Populated when empty or duplicate + members were dropped from key (naming each position and the key queried), or when a period bound was set but some observations carry a time_period label the range filter does not recognize; both texts appear when both apply. Composes with retrieval_guidance, staged or not, when both apply."
},
"source": {
"type": "string",
"description": "Attribution string required by IMF data terms: \"Source: International Monetary Fund, <dataflow name>, <link>\"."
},
"staged": {
"type": "boolean",
"description": "True when the complete observation set is stored on DataCanvas. canvas_id and table_name are present whenever true."
},
"canvas_id": {
"type": "string",
"description": "DataCanvas session ID — present when staged=true. Pass first to imf_dataframe_describe, then to imf_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True only when observations is an incomplete preview of observation_count. A result can be staged=true and truncated=false when every observation also fits inline, and staged=false and truncated=true when DataCanvas is not enabled and the full result exceeds the response budget."
},
"end_period": {
"type": "string",
"description": "Latest period covered; absent when the full available range was used."
},
"table_name": {
"type": "string",
"description": "DuckDB table name on the canvas — present when staged=true; reference in SQL via FROM <table_name>."
},
"dataflow_id": {
"type": "string",
"description": "Dataflow identifier that was queried, in its catalog spelling, e.g. WEO."
},
"observations": {
"type": "array",
"items": {
"type": "object",
"required": [
"series_key",
"time_period",
"value",
"status"
],
"properties": {
"value": {
"type": [
"number",
"null"
],
"description": "Observation value in base units, e.g. 29298025000000 for US GDP of $29.3 trillion; null when missing. The series' scale is already reflected in it: never apply scale to this value."
},
"status": {
"type": [
"string",
"null"
],
"description": "Observation status flag exactly as the dataflow publishes it, e.g. T, B, C, or NA; null when the observation carries none. The flags are not a shared vocabulary across dataflows. A null value with no status, or whose only status is the not-available marker NA or n.a. (any letter case), is omitted as padding; a null value with any other status is returned."
},
"series_key": {
"type": "string",
"description": "Dot-separated dimension codes identifying this series, e.g. USA.NGDP_RPCH.A. Matches the single-country equivalent of the query key — useful when a query covers multiple countries."
},
"time_period": {
"type": "string",
"description": "Time label as emitted by the upstream API. Annual: YYYY (e.g. 2023). Semi-annual: YYYY-SN (e.g. 2023-S1). Quarterly: YYYY-QN (e.g. 2023-Q1). Monthly: YYYY-MNN (e.g. 2023-M01, not YYYY-MM). Daily: YYYY-MM-DD (e.g. 2023-01-05). Every one of these is also accepted as a start_period/end_period bound, so a label from this field can be passed straight back in."
},
"reference_period": {
"type": "string",
"description": "This observation's own reference (base) period, exactly as published, e.g. 2010A or 2010M1. Present only when the observation carries one (CPI and GS_LEPM publish it); where the series-level value reads Multiple, it varies by observation. Never filled in from the series."
}
},
"description": "A single time-series observation.",
"additionalProperties": false
},
"description": "Inline observations, oldest period first. When truncated=true this is the budget-limited time-ascending prefix of the result; observation_count remains the full count."
},
"start_period": {
"type": "string",
"description": "Earliest period covered; absent when the full available range was used."
},
"missing_series": {
"type": "array",
"items": {
"type": "object",
"required": [
"series_key",
"reason"
],
"properties": {
"reason": {
"enum": [
"no_data",
"no_data_in_range"
],
"type": "string",
"description": "What a query for this series alone reports: no_data when it has no observations at all, no_data_in_range when it has some, but none inside start_period/end_period."
},
"series_key": {
"type": "string",
"description": "A requested series that returned no observation: one code per key position, * where the key has *, e.g. ASM.NGDP_RPCH.A."
},
"available_range": {
"type": "object",
"required": [
"first",
"last"
],
"properties": {
"last": {
"type": "string",
"description": "Latest time_period the series has."
},
"first": {
"type": "string",
"description": "Earliest time_period the series has."
}
},
"description": "With no_data_in_range: the window the series covers.",
"additionalProperties": false
}
},
"description": "One requested series the result does not carry.",
"additionalProperties": false
},
"description": "Requested series of a + key that returned no observation while others did, in key order, at most 20. A requested series is each combination of the codes listed at every position. Counted over the full result, so a series left out of a truncated preview is not listed. Absent when every requested series returned."
},
"series_metadata": {
"type": "array",
"items": {
"type": "object",
"required": [
"series_key",
"unit",
"scale",
"decimals"
],
"properties": {
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure for this series as the upstream code, e.g. PT (percent), USD, XDC (domestic currency). Null when the response carries none for it."
},
"scale": {
"type": [
"string",
"null"
],
"description": "Power of ten the IMF publishes this series in, as the upstream code: \"9\" is billions, \"0\" units. This series' observation values are already in base units."
},
"decimals": {
"type": [
"number",
"null"
],
"description": "Number of decimal places shown for this series."
},
"series_key": {
"type": "string",
"description": "Series these attributes belong to, matching observations[].series_key."
},
"reference_period": {
"type": "string",
"description": "This series' reference (base) period, exactly as published, e.g. 2010A or 2010=100. Present only when the series carries one."
}
},
"description": "Unit, scale, decimals, and reference period for one series in the result.",
"additionalProperties": false
},
"description": "Per-series attributes, one entry per distinct series_key in the result. Present only when the query resolved to more than one series; a single-series query carries its values in series_attributes instead. Unit and scale differ across series in one query — WEO NGDPD is USD published in billions (scale 9) while NGDP_RPCH is PT at scale 0 — so interpret each series against its own entry."
},
"observation_count": {
"type": "number",
"description": "Total observations in the result, after any last_n_observations selection."
},
"series_attributes": {
"type": "object",
"required": [
"unit",
"scale",
"decimals"
],
"properties": {
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of measure as the upstream code, e.g. PT (percent), USD, XDC (domestic currency), NUM (count). Null when the response carries no unit for the series — many dataflows publish none."
},
"scale": {
"type": [
"string",
"null"
],
"description": "Power of ten the IMF publishes this series in, as the upstream code: \"9\" is billions, \"6\" millions, \"0\" units. Observation values are already in base units, so the published figure is value / 10^scale."
},
"decimals": {
"type": [
"number",
"null"
],
"description": "Number of decimal places shown."
},
"reference_period": {
"type": "string",
"description": "Reference (base) period of an index series, exactly as published: free text such as 2010A, 2016M12, 2010=100, or Multiple (the observations carry their own). Present only when the series carries one; never parsed as a time_period."
}
},
"description": "Attributes of the first series in the result — the same series as series_metadata[0]. A key with + or * resolves to several series whose scale and unit differ, and this field describes only the first of them: read series_metadata for the rest, and never apply these values to another series_key.",
"additionalProperties": false
},
"retrieval_guidance": {
"type": "string",
"description": "Present on every staged result, where it names the imf_dataframe_describe-before-imf_dataframe_query retrieval workflow, and on a result truncated without DataCanvas, where it names the last time_period returned and how to narrow the query for the rest."
},
"last_n_observations": {
"type": "number",
"description": "The last_n_observations input, echoed when set: observations holds each series' last N in the range. Absent when every observation was returned."
},
"missing_series_count": {
"type": "number",
"description": "How many requested series returned no observation — the full count when missing_series stops at 20. Present with missing_series."
},
"unresolved_attributes": {
"type": "object",
"required": [
"concepts",
"series_count",
"guidance"
],
"properties": {
"concepts": {
"type": "array",
"items": {
"enum": [
"unit",
"scale",
"decimals"
],
"type": "string"
},
"description": "Attributes the recovery request failed to bring back, e.g. [\"unit\"]."
},
"guidance": {
"type": "string",
"description": "How to get them: retry, or query the key with a * it names (or a * at one position), which matches every code there, so keep only the series requested."
},
"series_count": {
"type": "number",
"description": "Series in the result whose value for a listed attribute is null."
}
},
"description": "Present only when a + key on the dimension an attribute is grouped by made the portal leave unit, scale, or decimals out, and the extra request that recovers them failed. A listed attribute that is null is then unknown, not unpublished. Absent when that request found no value — the dataflow publishes none — or was not needed.",
"additionalProperties": false
}
},
"additionalProperties": false
}imf_query_dataset annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}imf_dataframe_describe — Imf Dataframe Describe
Advertised read-only
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.
imf_dataframe_describe input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"canvas_id"
],
"properties": {
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID returned by imf_query_dataset whenever staged=true, from automatic spillover or output_mode=\"canvas\"."
}
},
"additionalProperties": false
}imf_dataframe_describe output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"canvas_id",
"tables",
"table_count"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_not_found"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"tables": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"row_count",
"columns"
],
"properties": {
"name": {
"type": "string",
"description": "Table name — use this in imf_dataframe_query SQL."
},
"columns": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name — use this in SELECT and WHERE clauses."
},
"type": {
"type": "string",
"description": "DuckDB column type, e.g. VARCHAR, DOUBLE, BIGINT."
}
},
"description": "A single column definition.",
"additionalProperties": false
},
"description": "Column schema for this table."
},
"row_count": {
"type": "number",
"description": "Number of rows in this table."
}
},
"description": "A single canvas table with its schema.",
"additionalProperties": false
},
"description": "All tables registered on this canvas."
},
"canvas_id": {
"type": "string",
"description": "Canvas session ID that was introspected."
},
"table_count": {
"type": "number",
"description": "Total number of tables on the canvas."
}
},
"additionalProperties": false
}imf_dataframe_describe annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}imf_dataframe_query — Imf Dataframe Query
Advertised read-only
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.
imf_dataframe_query input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"canvas_id",
"sql"
],
"properties": {
"sql": {
"type": "string",
"description": "Read-only SQL SELECT statement — exactly one statement, starting with SELECT or with a WITH … SELECT common table expression. 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."
},
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID returned by imf_query_dataset whenever staged=true. Call imf_dataframe_describe with it before writing SQL."
}
},
"additionalProperties": false
}imf_dataframe_query output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"row_count",
"truncated"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"description": "A result row — keys are the selected column names; values are the JSON form of each DuckDB type: number, string (BIGINT, DECIMAL, and dates included), boolean, null, or an object/array for STRUCT, LIST, and MAP.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Largest result-row prefix whose complete structured and formatted response fits the 100,000-character response budget, after the canvas row limit (default 10,000) is applied. Values and column names are always whole here; when a single row only fits with its long cells or column names clipped in the formatted table, listed there one name: value line per column, or replaced there by a one-line pointer to this field, it is returned alone."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_not_found",
"missing_table",
"invalid_sql",
"sql_not_permitted",
"sql_execution_error",
"response_too_large"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not match any registered DataCanvas session (expired, wrong session, or canvas disabled). `missing_table`: The canvas exists but sql references a table that is not staged on it — the table expired, was dropped, or the name is wrong. `invalid_sql`: sql is not a single SELECT statement (a leading WITH … SELECT counts as one), or it is SELECT-shaped but fails to prepare — unknown column, unknown function, or a syntax error. `sql_not_permitted`: sql parses as a SELECT but the read-only gate refuses it — it calls an external-data or PRAGMA table function, reads a system catalog, plans an operator outside the read-only allowlist, or names a file instead of a staged table. `sql_execution_error`: sql prepares but fails while it runs, such as a failed cast or an arithmetic overflow. `response_too_large`: The first result row alone exceeds the response budget as structured content, even with the formatted text reduced to a one-line pointer to it. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"row_count": {
"type": "number",
"description": "Number of materialized rows returned in rows. Always equals rows.length and never claims a pre-cap total."
},
"truncated": {
"type": "boolean",
"description": "True when DataCanvas capped the query at its row limit or the server omitted materialized rows to fit the response-size budget. Page the remainder with a stable ORDER BY plus LIMIT/OFFSET, or narrow the query with WHERE or aggregation."
}
},
"additionalProperties": false
}imf_dataframe_query annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
imf-guide
Route a macro question to the IMF dataflow that holds it and read imf_* results without mixing projections, group aggregates, or currency units. Use before calling imf_* tools for GDP, inflation, government debt, exchange rates, or cross-country comparisons, and when a catalog or codelist search finds nothing, a * key returns groups beside countries, or a long series needs splicing.
imf-guide URI
skill://imf-guide/SKILL.mdimf-database — IMF Dataflow Metadata
Metadata for a single IMF SDMX dataflow — dimensions with their concept-scheme labels and bounded codelist previews, counts, key_format, name, and description. Stable URI-addressable reference for known dataflow IDs (WEO, BOP, CPI, etc.).
imf-database URI template
imf://database/{dataflow_id}io.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 599 ms
- 95th percentile latency
- 599 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 599 ms · metadata changed · 5 tool(s), 1 resource(s), 2 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http imf-mcp-server-caseyjhand https://imf.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add imf-mcp-server-caseyjhand --url https://imf.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"imf-mcp-server-caseyjhand": {
"url": "https://imf.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"imf-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://imf.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"imf-mcp-server-caseyjhand": {
"type": "http",
"url": "https://imf.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http imf-mcp-server-caseyjhand https://imf.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://imf.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"imf-mcp-server-caseyjhand": {
"serverUrl": "https://imf.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like imf-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.