mcp-nbb

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)

# With uv (runs without installing globally)
uvx mcp-nbb

# Or install into a regular venv
pip install mcp-nbb

From source

git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip 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)

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

---

Tools

Tool	API calls	Purpose
nbb_search(query, …)	0	Fuzzy 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=…)	1	Generic data fetch. Either key (raw SDMX) or filters ({"FREQ":"D","EXR_CURRENCY":"USD"}).
nbb_quick(topic, …)	1	Topic-based shortcut for 18 common queries — see topic table below.
nbb_compare(series, …)	N	Align 2-5 series on a common time index, downsampling finer frequencies via closing aggregation.
nbb_status()	0	Diagnostic snapshot: catalog, cache, API config.

nbb_quick topics

Topic	Dataflow	Parameters
exchange_rate	BE2/DF_EXR	currency, frequency
policy_rate	BE2/DF_IRESCB	—
mortgage_rate	BE2/DF_MIR	—
long_term_yield	BE2/DF_IROLOYLD	—
inflation_hicp	BE2/DF_HICP_2025	—
inflation_national	BE2/DF_NICP_2025	—
ppi	BE2/DF_PPI	—
industrial_production	BE2/DF_INDPROD	—
gdp / gdp_growth	BE2/DF_QNA_DISS	—
unemployment_rate	BE2/DF_UNEMPLOY_RATE	—
employment	BE2/DF_EMPLOY_DISS	—
government_debt	BE2/DF_CGD	—
government_deficit	BE2/DF_NFGOV_NET_DISS	—
current_account	BE2/DF_BOPBPM6	—
consumer_confidence	BE2/DF_CONSN	—
business_confidence	BE2/DF_BUSSURVM	—
`trad

... View full README on GitHub