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

nbb_quick topics

Resources

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.

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:

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:

pip install -e ".[dev]"
pytest                     # full suite (unit + integration + E2E)
pytest -m "not e2e"        # fast subset
ruff check src tests
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 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.