sdmx-data-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sdmx-data-mcp how much do Swiss banks have in foreign claims since 2020?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sdmx-data-mcp
An MCP server that lets an AI assistant discover and retrieve official statistics from SDMX services.
Built on the BIS's own pysdmx library.
Why this exists
Other SDMX MCP servers navigate metadata well and then hand back a query URL. The assistant ends up with a link, not numbers — and cannot answer the question it was asked.
sdmx-data-mcp finishes the job. get_data returns the observations.
Related MCP server: Countries MCP Server
Quick start
pip install sdmx-data-mcpThen register it with your client:
claude mcp add sdmx -- sdmx-data-mcpThat is the whole setup. Ask your assistant something like "what is the Swiss policy rate since 2020?" and it will find the dataflow, check what it can filter on, and come back with the actual series.
Claude Desktop — in claude_desktop_config.json:
{
"mcpServers": {
"sdmx": {
"command": "sdmx-data-mcp"
}
}
}Cursor — in .cursor/mcp.json:
{
"mcpServers": {
"sdmx": {
"command": "sdmx-data-mcp"
}
}
}If sdmx-data-mcp is not on your PATH, use the absolute path to the
executable, or "command": "python", "args": ["-m", "sdmx_data_mcp"].
Over HTTP, to share one instance:
sdmx-data-mcp --transport http --host 127.0.0.1 --port 8000The four tools
Meant to be called in order. Only the last one moves data.
Tool | Purpose |
| Known endpoints, plus any SDMX-REST v2 base URL you supply |
| One |
| Components, available codes, size signals |
| Retrieves the observations |
A real session
Transcripts below are actual tool output, not illustrations. More in docs/EXAMPLES.md.
1. Find the dataflow
search_dataflows(query="policy rate central bank")
{
"search_terms": ["policy", "rate", "central", "bank"],
"total_dataflows_on_service": 32,
"match_count": 12,
"dataflows": [
{ "ref": "BIS:WS_CBPOL(1.0)", "name": "Central bank policy rates",
"matched_on": "name" },
{ "ref": "BIS:WS_CBS_PUB(1.0)", "name": "Consolidated banking",
"matched_on": "name" }
// ...
]
}One request to the service; the terms are matched locally. Searching for synonyms costs nothing extra, so put them all in one query.
2. See what you can filter on
inspect_dataflow(ref="BIS:WS_CBPOL(1.0)", find_code="CH")
{
"series_count": 98,
"obs_count": null, // BIS does not report this
"size_warning": null, // small enough to retrieve
"dimensions": [
{ "id": "FREQ", "name": "Frequency", "code_count": 2,
"codes": [{"id": "D", "name": "Daily"}, {"id": "M", "name": "Monthly"}] },
{ "id": "REF_AREA", "name": "Reference area", "code_count": 49,
"codes": [ /* ... */ {"id": "CH", "name": "Switzerland"} /* ... */ ] }
]
}3. Get the numbers
get_data(
ref="BIS:WS_CBPOL(1.0)",
filters="FREQ = 'M' AND REF_AREA = 'CH' AND TIME_PERIOD >= '2020-01'",
columns=["OBS_VALUE"],
)
{
"filter_applied": "FREQ = 'M' AND REF_AREA = 'CH' AND TIME_PERIOD >= '2020-01'",
"filter_fallback": null,
"row_count": 79,
"total_rows_available": 79,
"truncated": false,
"records": [
{"SERIES_KEY": "M.CH", "OBS_VALUE": "-0.75", "TIME_PERIOD": "2020-01"},
{"SERIES_KEY": "M.CH", "OBS_VALUE": "-0.75", "TIME_PERIOD": "2020-02"}
// ...
],
"next_step": "Complete: all 79 matching rows were returned. Safe to aggregate."
}truncated: false and row_count == total_rows_available, so this really is
the whole series and it is safe to average or chart.
Several values of one component
The query parser accepts AND but not OR. Use IN (...):
get_data(
ref="BIS:WS_XRU(1.0)",
filters="FREQ = 'M' AND CURRENCY IN ('CHF', 'KES') AND TIME_PERIOD >= '2026-01'",
columns=["OBS_VALUE"],
)
{ "row_count": 14, "truncated": false, "records": [
{"SERIES_KEY": "M.CH.CHF.E", "OBS_VALUE": "0.768269", "TIME_PERIOD": "2026-01"},
{"SERIES_KEY": "M.KE.KES.A", "OBS_VALUE": "129.126615", "TIME_PERIOD": "2025-12"}
// ...
] }With both legs retrieved, an assistant can compute what neither service publishes — a CHF/KES cross rate — and correctly note that the newest period the two currencies share is December 2025, because KES lags CHF.
What the server enforces
These rules are handled by the server rather than left for the assistant to remember. Each one prevents a specific class of confidently wrong answer.
Conjunctions only. AND between clauses, never OR. Several values of one
component use IN ('A', 'B').
Availability is not validity. inspect_dataflow reports codes for which
data currently exist. A code missing from that list may still be valid in the
full codelist, so its absence is never reported as proof that something does
not exist.
Ambiguous codes are surfaced, not guessed. On BIS consolidated banking,
CH is available in three components at once — reporting country, counterparty
country, and a bank type that happens to share the country codelist:
inspect_dataflow(ref="BIS:WS_CBS_PUB(1.0)", find_code="CH")
{ "code_locations": [
{"component_id": "L_REP_CTY", "role_hint": "reporting country"},
{"component_id": "CBS_BANK_TYPE", "role_hint": "bank type (shares a country codelist)"},
{"component_id": "L_CP_COUNTRY", "role_hint": "counterparty country"}
],
"next_step": "That code is ambiguous - it appears in 3 components ..." }Claims by Swiss banks and claims on Switzerland are different questions. The server makes the assistant choose rather than silently pick one.
Size before retrieval. obs_count is frequently unreported — the BIS
returns null for it on both full and filtered scopes — so series_count is
the signal relied on. A size_warning appears when retrieval would truncate.
Truncation is not sampling. When truncated is true, the rows are the
first N in service order, and next_step says so explicitly:
Truncated: 112,648 rows matched but only 500 were returned. These are the first rows in service order, not a sample — do not compute totals or averages from them.
Time filters degrade gracefully. TIME_PERIOD is pushed down to the
service first. On a client-side rejection the clause is stripped, the narrower
query is retried, and the cutoff is applied with pandas — reported in
filter_fallback. It deliberately does not fall back on NotFound,
Unavailable or InternalError, where dropping a clause cannot help and would
only obscure the real error.
Errors keep their meaning. The pysdmx error hierarchy is preserved rather than flattened, so an assistant can tell a transient outage from a bad reference instead of retrying blindly or giving up too early:
[internal_error] Unexpected message format - The payload could not be
deserialized. | retriable=false | next_step: The service failed, or returned a
response that could not be parsed. Do not repeat the identical call - narrow
the filter or try a different dataflow, since the fault is server-side.Kind | Retriable | Means |
| yes | Service unreachable; retry after a delay |
| yes | Transient failure |
| no | Resource does not exist; do not repeat |
| no | Malformed filter; check syntax and code IDs |
| no | Credentials rejected |
| no | Service lacks the required API |
| no | Server-side fault; narrow or change the query |
| no | Bug in this server; please report it |
Services
pysdmx.api.dc.Endpoints currently ships exactly one endpoint, the BIS. Every
tool therefore takes a service argument accepting any SDMX-REST v2 base
URL as a first-class input, not a fallback:
search_dataflows(query="prices", service="https://your-service.org/api/v2")The service must return structural metadata as SDMX-JSON 2.0.0 and data as SDMX-CSV. Other providers (ECB, OECD, IMF, Eurostat, ILO) are deliberately not hardcoded: each needs verifying against those requirements first, and listing them unverified would invite confident failures.
Development
pip install -e ".[dev]"
ruff format && ruff check && mypy
pytest --cov=sdmx_data_mcp --cov-branch --cov-report=term-missing162 tests at 100% statement and branch coverage, mypy in strict mode, CI across Linux, Windows and macOS on Python 3.10–3.13.
Most server tests inject a fake connector so every branch is reachable
deterministically. A separate end-to-end module drives the real
PandasConnector against respx-mocked responses, so drift in URL
construction or SDMX-CSV parsing surfaces there.
Relationship to pysdmx
This package depends on pysdmx[data] from PyPI. It does not fork or vendor
it, and uses only the public API — PandasConnector, Endpoints and the
errors hierarchy.
The same server has also been proposed upstream as bis-med-it/pysdmx#669. This package exists so it is installable today regardless of what happens there.
Licence
Apache-2.0. See LICENSE.
Available Tools
4 toolsget_dataA
Retrieve observations as records. This returns the actual numbers.
Call inspect_dataflow first to confirm component and code IDs and to check the size of what you are about to pull.
If a TIME_PERIOD clause is rejected by the service, it is retried without that clause and the cutoff is applied locally; the response says so in filter_fallback.
Returns: The observations, the filter actually sent, and a truncated flag. When truncated, the rows are the first N in service order and are NOT a representative sample.
Raises: ToolError: If retrieval fails. The message carries a [kind] discriminator and a retry hint.
Inputs: ref (required), limit, labels, columns, +2 more. Returns: Result of the ``get_data`` tool - the observations themselves.
inspect_dataflowA
Inspect a dataflow's components, available codes and size.
Call this before get_data. It answers three questions: what can I filter on, which codes actually have data, and is this small enough to retrieve?
If you only need to know whether data exist for some subset, pass filters and stop here rather than going on to get_data.
Returns: Components grouped by role, availability-backed codes, and size signals with a warning when retrieval would truncate.
Raises: ToolError: If the dataflow is not found or the request fails.
Inputs: ref (required), filters, service, find_code. Returns: Result of the ``inspect_dataflow`` tool.
list_servicesA
List the SDMX services this server can query.
Any SDMX-REST v2 base URL also works: pass it as the service argument to any other tool. The service must return structural metadata as SDMX-JSON 2.0.0 and data as SDMX-CSV.
Returns: The known services, with capability notes for each.
Inputs: no named parameters. Returns: Result of the ``list_services`` tool.
search_dataflowsA
Find dataflows (datasets) matching a topic.
Issues exactly one request to the service and matches the terms locally, so searching for synonyms costs nothing extra: put them all in one query rather than calling this repeatedly.
Returns: Matching dataflows, each with a ref to pass to the next tool.
Raises: ToolError: If the service is unknown or the request fails. The message carries a [kind] discriminator and a retry hint.
Inputs: limit, query, service. Returns: Result of the ``search_dataflows`` tool.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct stage of an SDMX query workflow: discovering services, finding dataflows, inspecting a dataflow, and fetching data. There is no overlap in purpose, and the descriptions explicitly position each tool relative to the next.
All tool names follow a consistent verb_noun snake_case pattern: list_services, search_dataflows, inspect_dataflow, get_data. The minor singular/plural variation between dataflows and dataflow is natural and does not create confusion.
Four tools is a well-scoped size for a focused SDMX data retrieval server. Each tool is necessary and corresponds to a meaningful step in the pipeline without redundancy or bloat.
The tool surface covers the full read-only workflow: discovering available services, locating relevant dataflows, understanding their structure and constraints, and retrieving actual observations. No critical operations are missing for the stated purpose.
Maintenance
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceA model Context Protocol (MCP) server that provides comprehensive OECD statistics through the SDMX API, supporting AI assistants and chatbots to query OECD datasets in areas such as economy, health, education, and environment.92Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP Server that gives AI assistants access to comprehensive country data from 250+ countries.1MIT
- AlicenseBqualityDmaintenanceMCP server for accessing Japanese government statistics portal 'e-Stat' API, enabling language models to search and retrieve statistical data.587 PyPI21MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that lets AI agents discover and call R and Python statistical functions without writing code.-