mcp-nbb
Provides tools for querying the National Bank of Belgium's SDMX statistical API (NSI Web Service). Exposes 223 Belgian and IMF/SDDS dataflows through search and describe tools backed by a bundled enriched catalogue, a generic data query tool accepting raw SDMX keys or dimension filters, a quick headline-series tool for 18 common topics (exchange rates, policy/mortgage rates, inflation, GDP, unemployment, government debt, trade balance, confidence indicators), and a series comparison tool that aligns 2-5 series on a common time index. Includes browsable resources for the dataflow catalogue, individual dataflows, and categories, plus pagination, truncation hints, and diagnostic error codes.
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., "@mcp-nbb What's the EUR/USD exchange rate over the last month?"
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.
mcp-nbb
MCP server for the National Bank of Belgium SDMX statistical API.
Exposes the 223 NBB dataflows (195 BE2 + 28 IMF/SDDS) as 6 LLM-friendly tools and 3 browsable resources, with a bundled enriched catalogue so the LLM can discover, describe, and query dataflows without redundant API calls.
Upstream:
https://nsidisseminate-stat.nbb.be/rest(NSI Web Service v8)Transport: stdio (standard MCP)
Python: 3.11 – 3.14
MCP SDK:
mcp2.xPlatforms: Linux, macOS, Windows
223 dataflows classified into 14 categories — see DATAFLOWS_CATALOG.md
Install
From PyPI (recommended)
# With uv (runs without installing globally)
uvx mcp-nbb
# Or install into a regular venv
pip install mcp-nbbFrom source
git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip install -e .The package ships with the full enriched catalogue (~6 MB under
src/nbb_mcp/data/catalog/). No build step is required for regular use.
Upgrading from 0.1.x: 0.1.2 cannot start on a fresh install because
mcp2.x removed theFastMCPmodule it imported. Version 0.2.0 targetsmcp2.x; runuvx mcp-nbb@latestorpip install -U mcp-nbb.
Related MCP server: OECD MCP Server
Client configuration
Claude Code
claude mcp add nbb -- uvx mcp-nbbClaude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on
macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, or the
equivalent on Linux.
Using uvx (recommended)
{
"mcpServers": {
"nbb": {
"command": "uvx",
"args": ["mcp-nbb"]
}
}
}From a local editable install
macOS / Linux:
{
"mcpServers": {
"nbb": {
"command": "/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb"
}
}
}Windows:
{
"mcpServers": {
"nbb": {
"command": "C:\\Users\\you\\projects\\mcp-nbb\\.venv\\Scripts\\mcp-nbb.exe"
}
}
}Restart Claude Desktop — the 6 nbb_* tools appear in the MCP panel.
All tools are read-only; the catalogue tools (nbb_search, nbb_describe,
nbb_status) never leave the process, which the tool annotations declare.
Tools
Tool | API calls | Purpose |
| 0 | Fuzzy search over the local fiches (en/fr/nl/de), with available frequencies and time coverage. |
| 0 (default) | Full enriched fiche — dimensions with the codes that actually hold data, frequencies, time coverage, key template, common queries. |
| 1 | Generic data fetch. Either |
| 1 | Headline series for 18 common topics — see topic table below. Last 24 observations unless a period window is given. |
| N | Align 2-5 single series on a common time index, downsampling finer frequencies via closing aggregation ( |
| 0 | Diagnostic snapshot: catalog, cache, API config and per-process usage counters. |
nbb_quick topics
Every topic resolves to one headline series. frequency (A/S/Q/M/D) overrides
the default on any topic and is validated against the frequencies the flow
actually publishes; currency only applies to exchange_rate.
Topic | Dataflow | Headline series (default frequency) |
|
| EUR vs |
|
| ECB deposit facility rate (D) |
|
| Cost of borrowing, households, house purchase (M) |
|
| Belgian 10-year OLO yield (D) |
|
| HICP all items, % change (M) |
|
| National CPI general index, % change (M) |
|
| Producer prices, general index, total market (M) |
|
| Total industry B-D, calendar adjusted (M) |
|
| GDP chain-linked volume / q-o-q %, SA (Q) |
|
| Harmonised rate, total, SA (M) |
|
| Total domestic employment, SA (Q) |
|
| General government consolidated gross debt (Q) |
|
| Net lending/borrowing, % of GDP (A) |
|
| Current account, net (Q) |
|
| Consumer confidence indicator (M) |
|
| Business barometer, smoothed (M) |
|
| Goods trade balance with the world (M) |
Responses and errors
Data tools return summary (series count, total observations, period range),
series (per-series stats: first/latest, min/max/mean, change), data (rows)
and metadata. Two budgets keep a response inside the model's context:
max_observations (rows, default 200) and max_series (per-series stats,
default 20). When either one cuts, truncated is true and next_page_hint
says why and names the oldest returned period. format is summary
(default), table (rows without per-series stats) or series (rows grouped
by series).
Errors come back as tool errors whose text starts with a code and carries the data needed to fix the call:
[UNKNOWN_CODE] Unknown code(s) ['D'] for dimension 'FREQ' on BE2/DF_QNA_DISS
details: {"dimension": "FREQ", "invalid_codes": ["D"], "valid_codes_sample": ["A", "Q"], ...}Main codes: UNKNOWN_FLOW (with did_you_mean), UNKNOWN_DIMENSION,
UNKNOWN_CODE, UNKNOWN_TOPIC, AMBIGUOUS_SERIES, FREQUENCY_TOO_FINE,
INVALID_FORMAT, NOT_FOUND, TIMEOUT, WAF_BLOCK.
Resources
URI | Content |
| Markdown index of all dataflows by category. |
| Full enriched fiche for one flow. |
| All flows in a category. |
Example prompts in Claude
"What's the EUR/USD exchange rate over the last month?" →
nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)
"Compare Belgian GDP growth to the unemployment rate since 2020." →
nbb_compare([{dataflow_id:"DF_QNA_DISS",key:"Q.2.B1GM.VZ.LQ.Y",label:"GDP q/q"}, {dataflow_id:"DF_UNEMPLOY_RATE",key:"M.AA.Z0000.Y.BE.HUR.RATE",label:"Unemployment"}], start_period="2020-Q1")(each spec must match exactly one series — an ambiguous key returnsAMBIGUOUS_SERIESwith sample keys)
"Find NBB dataflows about consumer credit." →
nbb_search("consumer credit")→nbb_describe(...)→nbb_query(...).
Configuration (environment variables)
All settings have sensible defaults; override via environment variables.
Variable | Default | Purpose |
|
| SDMX REST base URL |
|
| Per-request timeout (s) |
| browser UA | Required for the WAF — default is a valid Chrome UA string |
|
| Required for the WAF |
|
| Persistent disk cache |
| OS cache dir | Override cache location (defaults to |
|
| TTL for data responses (s) |
|
| TTL for structure responses (s) |
|
| Self-imposed rate limit (req/period) |
|
| Rate limit window (s) |
|
| Attempts on transient errors (>= 1) |
|
| First backoff delay (s) |
|
| Maximum backoff delay (s) |
|
|
|
|
|
|
An invalid value (NBB_API_TIMEOUT=abc, NBB_RETRY_ATTEMPTS=0,
NBB_LOG_LEVEL=LOUD…) stops the server with a ConfigError naming the
variable instead of silently falling back to the default. Logs go to stderr;
stdout is reserved for the MCP protocol.
The default cache path resolves to:
Linux:
~/.cache/mcp-nbb/macOS:
~/Library/Caches/mcp-nbb/Windows:
%LOCALAPPDATA%\mcp-nbb\Cache\
Refreshing the catalogue
The bundled src/nbb_mcp/data/catalog/ snapshot is regenerated by fetching,
for each dataflow, the DSD + codelists and the actual content constraint
(availableconstraint): codes that hold data, frequencies, time coverage and
observation count:
mcp-nbb-build-catalog --forceOptions:
--force— rebuild every fiche, ignoring existing ones.--limit N— only process the first N flows (debug).--only BE2/DF_EXR,BE2/DF_HICP_2025— rebuild specific flows.--concurrency 5— parallel DSD requests.--timeout 120— per-request timeout (availability queries on the large external-trade flows exceed the interactive 30 s default).
A full rebuild takes ~6 minutes against the live API. Catalogue footprint is ~6 MB: codelists are narrowed to codes that hold data and truncated to 200 codes per dimension.
A weekly GitHub Action (build-catalog.yml) rebuilds the catalogue, runs the
full test suite on it, and opens a PR if structural drift is detected
(coverage/observation counts alone refresh at most every 90 days).
Troubleshooting
"WAF returned an HTML redirect"
The NBB API is behind a WAF that returns an HTML 200 redirect for any request
without a browser-like User-Agent and an Origin: https://dataexplorer.nbb.be
header. The client injects both by default. If you override NBB_USER_AGENT,
keep a genuine-looking browser string.
"HTTP 404 NoResultsFound" or an empty result
The SDMX key didn't match any series in that period. nbb_describe(dataflow_id)
lists, per dimension, only the codes that hold data, plus the flow's
time_coverage — a valid code combination can still be empty, and periods
outside the coverage return nothing. Empty results include a next_page_hint
with the coverage and key template.
"truncated": true
Every data response is capped at max_observations=200 rows and
max_series=20 per-series stats by default. next_page_hint names the oldest
returned period; pass an earlier end_period, raise the caps, or narrow the
key. Errors carry a [CODE] and a details JSON (valid dimensions, codes,
did_you_mean) the model can act on.
Catalogue not found
If you run without the bundled src/nbb_mcp/data/catalog/, run
mcp-nbb-build-catalog once to populate it.
Development
See CONTRIBUTING.md for the full dev workflow. Short form:
pip install -e ".[dev]"
pytest # full suite (unit + integration + E2E)
pytest -m "not e2e" # fast subset
ruff check src tests && ruff format --check src tests
mypy src # strict
mcp-nbb-build-catalog # refresh the bundled catalogue
mcp-nbb # run the server (stdio)CI runs on Linux, macOS and Windows with Python 3.11 – 3.14, plus a job on the
lowest declared dependency versions, ruff + mypy --strict, and a wheel
check that the bundled catalogue matches _index.json. See
DATAFLOWS_CATALOG.md for the classified inventory.
Security
Please report vulnerabilities privately — see SECURITY.md.
License
MIT — see LICENSE for the full text.
Disclaimer
This project is not affiliated with or endorsed by the National Bank of
Belgium. It is an independent client of their public SDMX REST API. The
browser-like User-Agent and Origin headers are required by the upstream
WAF and used solely to access public statistical data. Users are responsible
for complying with NBB's terms of use.
Available Tools
6 toolsnbb_compareARead-onlyIdempotent
Align 2-5 SDMX series on a common time index. Each series is specified as {dataflow_id, agency?, key? | filters?, label?} and must resolve to a single series. Downsamples finer frequencies to the coarsest using closing (last-of-period) aggregation.
Inputs: series (required), frequency, end_period, max_periods, +1 more. Returns: object
nbb_describeBRead-onlyIdempotent
Return the full enriched fiche for a dataflow (dimensions with the codes that actually hold data, multilingual names, frequencies, time coverage, common queries). Reads from the local catalogue by default; pass force_refresh=True to revalidate the structure against the live API.
Inputs: dataflow_id (required), agency, language, force_refresh, +1 more. Returns: object
nbb_queryARead-onlyIdempotent
Generic SDMX data fetch. Specify either 'key' (raw SDMX, e.g. 'D.USD') or 'filters' ({'FREQ':'D','EXR_CURRENCY':'USD'}; a list value means OR). Supports start_period, end_period, last/first_n_observations (per series). max_observations caps returned rows and max_series caps per-series stats to keep the response within the model's context budget.
Inputs: dataflow_id (required), key, agency, format, +8 more. Returns: object
nbb_quickARead-onlyIdempotent
Topic-based shortcut for common queries (exchange_rate, inflation_hicp, gdp, unemployment_rate, government_debt, policy_rate, mortgage_rate, consumer_confidence, trade_balance, …). Routes to the right dataflow and headline series. 'frequency' (A/S/Q/M/D) applies to every topic; 'currency' only to exchange_rate, e.g. nbb_quick('exchange_rate', currency='USD').
Inputs: topic (required), format, currency, frequency, +5 more. Returns: object
nbb_searchARead-onlyIdempotent
Fuzzy search across the local catalogue of NBB dataflows (no API call). Filters by category and agency. Returns ranked hits with dimensions, available frequencies, time coverage and example queries.
Inputs: query (required), limit, agency, category, +2 more. Returns: object
nbb_statusARead-onlyIdempotent
Diagnostic snapshot: catalogue stats, HTTP cache footprint, API config and usage.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role: nbb_status is diagnostics, nbb_search/nbb_describe are discovery layers, nbb_query is generic fetch, nbb_quick is a topic shortcut, and nbb_compare is alignment. The main overlap is nbb_quick vs nbb_query (quick routes to predefined dataflows), but descriptions make the boundary clear enough for an agent to choose correctly.
All six tools follow a uniform nbb_<verb/noun> snake_case pattern with single-word suffixes. No mixing of styles or casing conventions.
Six tools is well-scoped for an SDMX data-access server: discovery, description, generic query, quick query, comparison, and diagnostics. Each earns its place without redundancy.
The surface covers the full workflow: search → describe → query/quick → compare, plus status diagnostics. Minor gap: no explicit tool to enumerate categories/agencies or browse all dataflows, though nbb_search filters likely suffice as a workaround.
Maintenance
Related MCP Connectors
Belgian official open data: dataset search, Statbel figures, air, rivers, weather and trains.
Search and query 1,500+ OECD statistical datasets via SDMX. Keyless.
Query IMF SDMX 3.0 macroeconomic dataflows — WEO, BOP, CPI, exchange rates, 190 countries.
Macroeconomic and other official data from 170+ publishers, resolved from natural language with provenance.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides access to European Central Bank statistical data through SDMX data flows, enabling querying and listing of data flows via natural language or direct tool calls.160 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables searching, exploring, and querying over 1,500 OECD statistical datasets via SDMX, covering national accounts, employment, trade, PISA, health, and more.204 npm5Apache 2.0

@pipeworx/bisofficial
AlicenseNot gradedqualityCmaintenanceEnables querying Bank for International Settlements central-bank and global financial statistics via the SDMX v2 API, including credit-to-GDP gaps, curated dataflows, and full registry search with dataset fetching, without authentication.66 npm1MIT- AlicenseNot gradedqualityAmaintenanceEnables users to browse, search, and retrieve over 800,000 economic time series, with support for transformations, frequency aggregation, and date-range filtering.288 npmAGPL 3.0