Mcp Nbb

io.github.lacausecryptoPublished by GitHub account lacausecryptov0.1.2Updated Oct 24, 2026

MCP server for the National Bank of Belgium SDMX statistical API (221 dataflows).

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

A local MCP server that lets an assistant search, describe and query the National Bank of Belgium's SDMX statistical API, covering 221 dataflows.

What you can do
Search and describe dataflows: fuzzy search over a bundled catalogue of 221 dataflows in four languages, and full fiches with dimensions, codelists and key templates, without API calls. Fetch data: generic SDMX queries by raw key or by dimension filters, plus topic shortcuts for 18 common indicators such as exchange rates, policy and mortgage rates, inflation, GDP, unemployment and government debt. Compare series: align two to five series on a common time index, downsampling finer frequencies. Browse resources: a catalogue index, per-dataflow fiches and per-category listings. Check status: a diagnostic snapshot of catalogue, cache and API configuration.
When to use it
Useful when you need Belgian and euro-area macroeconomic or financial statistics from the NBB inside a conversation, for example looking up an exchange rate, comparing GDP growth with unemployment, or finding which dataflow covers a topic.
Requirements
Runs locally over stdio as a Python package (Python 3.11+), typically launched with uvx or pip. Needs network access to the NBB SDMX REST endpoint. No account or API key; optional environment variables tune the API base URL, timeout, cache, rate limits, retries and logging.
Before you install
Queries go to a third-party public API behind a WAF that requires browser-like User-Agent and Origin headers, which the client injects by default; overriding NBB_USER_AGENT may break access. The project is independent and not endorsed by the National Bank of Belgium, and users are responsible for complying with its terms of use. Responses are truncated at 200 observations by default. A persistent disk cache is enabled by default.

Installation

In SourceWeft

  1. Open Mcp Nbb in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-nbb

[CI] [PyPI version] [Python versions] [License: MIT] [MCP compatible]

MCP server for the National Bank of Belgium SDMX statistical API.

Exposes the 221 NBB dataflows (194 BE2 + 27 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+
  • Platforms: Linux, macOS, Windows
  • 221 dataflows classified into 14 categories — see DATAFLOWS_CATALOG.md

Install

From PyPI (recommended)

bash
# With uv (runs without installing globally)uvx mcp-nbb
# Or install into a regular venvpip install mcp-nbb

From source

bash
git clone https://github.com/lacausecrypto/mcp-nbb.gitcd mcp-nbbpip install -e .

The package ships with the full enriched catalogue (~9 MB under src/nbb_mcp/data/catalog/). No build step is required for regular use.

Claude Desktop configuration

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 once published to PyPI)

json
{  "mcpServers": {    "nbb": {      "command": "uvx",      "args": ["mcp-nbb"]    }  }}

From a local editable install

macOS / Linux:

json
{  "mcpServers": {    "nbb": {      "command": "/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb"    }  }}

Windows:

json
{  "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.

Tools

ToolAPI callsPurpose
nbb_search(query, …)0Fuzzy search over the 221 local fiches (en/fr/nl/de).
nbb_describe(dataflow_id, …)0 (default)Full enriched fiche — dimensions, codelists, key template, common queries. force_refresh=True revalidates live.
nbb_query(dataflow_id, key=…, filters=…)1Generic data fetch. Either key (raw SDMX) or filters ({"FREQ":"D","EXR_CURRENCY":"USD"}).
nbb_quick(topic, …)1Topic-based shortcut for 18 common queries — see topic table below.
nbb_compare(series, …)NAlign 2-5 series on a common time index, downsampling finer frequencies via closing aggregation.
nbb_status()0Diagnostic snapshot: catalog, cache, API config.

nbb_quick topics

TopicDataflowParameters
exchange_rateBE2/DF_EXRcurrency, frequency
policy_rateBE2/DF_IRESCB—
mortgage_rateBE2/DF_MIR—
long_term_yieldBE2/DF_IROLOYLD—
inflation_hicpBE2/DF_HICP_2025—
inflation_nationalBE2/DF_NICP_2025—
ppiBE2/DF_PPI—
industrial_productionBE2/DF_INDPROD—
gdp / gdp_growthBE2/DF_QNA_DISS—
unemployment_rateBE2/DF_UNEMPLOY_RATE—
employmentBE2/DF_EMPLOY_DISS—
government_debtBE2/DF_CGD—
government_deficitBE2/DF_NFGOV_NET_DISS—
current_accountBE2/DF_BOPBPM6—
consumer_confidenceBE2/DF_CONSN—
business_confidenceBE2/DF_BUSSURVM—
trade_balanceBE2/DF_EXTERNAL_TRADE_OVERVIEW—

Resources

URIContent
nbb://catalogMarkdown index of all 221 dataflows by category.
nbb://dataflow/{agency}/{dataflow_id}Full enriched fiche for one flow.
nbb://category/{category}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",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

"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.

VariableDefaultPurpose
NBB_API_BASE_URLhttps://nsidisseminate-stat.nbb.be/restSDMX REST base URL
NBB_API_TIMEOUT30Per-request timeout (s)
NBB_USER_AGENTbrowser UARequired for the WAF — default is a valid Chrome UA string
NBB_ORIGINhttps://dataexplorer.nbb.beRequired for the WAF
NBB_HTTP_CACHE_ENABLEDtruePersistent disk cache
NBB_HTTP_CACHE_PATHOS cache dirOverride cache location (defaults to platformdirs.user_cache_dir)
NBB_MEMORY_CACHE_TTL_DATA300TTL for data responses (s)
NBB_MEMORY_CACHE_TTL_STRUCTURE3600TTL for structure responses (s)
NBB_RATE_LIMIT_REQUESTS100Self-imposed rate limit (req/period)
NBB_RATE_LIMIT_PERIOD60Rate limit window (s)
NBB_RETRY_ATTEMPTS3Retries on transient errors
NBB_LOG_LEVELINFODEBUG/INFO/WARNING/ERROR
NBB_LOG_FORMATjsonjson or console

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 the DSD + codelists for each of the 221 dataflows:

bash
mcp-nbb-build-catalog --force

Options:

  • --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.

A full rebuild takes ~80 seconds against the live API. Catalogue footprint is capped at ~9 MB by truncating codelists to 200 codes per dimension (some IMF flows have 65 000+ codes).

A weekly GitHub Action (build-catalog.yml) rebuilds the catalogue and opens a PR if drift is detected.

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" on a data query

The SDMX key didn't match any series. Use nbb_describe(dataflow_id) to see valid codes, or pass filters={} / key="all" to retrieve everything and then narrow via start_period/end_period.

"Too many observations, truncated"

Every data response is capped at max_observations=200 by default. Increase via nbb_query(max_observations=1000) or narrow the query with a period window.

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:

bash
pip install -e ".[dev]"pytest                     # full suite (unit + integration + E2E)pytest -m "not e2e"        # fast subsetruff check src testsmcp-nbb-build-catalog      # refresh the bundled cataloguemcp-nbb                    # run the server (stdio)

CI runs on Linux, macOS and Windows with Python 3.11 and 3.12. 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.

Source: README.md at commit 8816b6b

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts