mcp-nbb

MCP-Server für die National Bank of Belgium SDMX-Statistik-API.

Stellt die 221 NBB-Datenflüsse (194 BE2 + 27 IMF/SDDS) als 6 LLM-freundliche Tools und 3 durchsuchbare Ressourcen bereit, mit einem gebündelten angereicherten Katalog, damit das LLM Datenflüsse ohne redundante API-Aufrufe entdecken, beschreiben und abfragen kann.

• Upstream: https://nsidisseminate-stat.nbb.be/rest (NSI Web Service v8)

• Transport: stdio (Standard-MCP)

• Python: 3.11+

• Plattformen: Linux, macOS, Windows

• 221 Datenflüsse in 14 Kategorien eingeteilt – siehe DATAFLOWS_CATALOG.md

Installation

Von PyPI (empfohlen)

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

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

Aus dem Quellcode

git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip install -e .

Das Paket enthält den vollständigen angereicherten Katalog (~9 MB unter src/nbb_mcp/data/catalog/). Für den regulären Gebrauch ist kein Build-Schritt erforderlich.

Related MCP server: OECD MCP Server

Claude Desktop-Konfiguration

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS, %APPDATA%\Claude\claude_desktop_config.json unter Windows oder das entsprechende unter Linux.

Verwendung von uvx (empfohlen, sobald auf PyPI veröffentlicht)

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

Aus einer lokalen Editable-Installation

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

Starten Sie Claude Desktop neu – die 6 nbb_*-Tools erscheinen im MCP-Bedienfeld.

Tools

nbb_quick-Themen

Ressourcen

Beispiel-Prompts in Claude

„Wie war der EUR/USD-Wechselkurs im letzten Monat?“ → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

„Vergleichen Sie das belgische BIP-Wachstum mit der Arbeitslosenquote seit 2020.“ → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

„Finden Sie NBB-Datenflüsse zu Verbraucherkrediten.“ → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...).

Konfiguration (Umgebungsvariablen)

Alle Einstellungen haben sinnvolle Standardwerte; überschreiben Sie sie über Umgebungsvariablen.

Der Standard-Cache-Pfad lautet:

• Linux: ~/.cache/mcp-nbb/

• macOS: ~/Library/Caches/mcp-nbb/

• Windows: %LOCALAPPDATA%\mcp-nbb\Cache\

Aktualisieren des Katalogs

Der gebündelte Schnappschuss src/nbb_mcp/data/catalog/ wird neu erzeugt, indem die DSD + Codelisten für jeden der 221 Datenflüsse abgerufen werden:

mcp-nbb-build-catalog --force

Optionen:

• --force – jedes Datenblatt neu erstellen, vorhandene ignorieren.

• --limit N – nur die ersten N Flüsse verarbeiten (Debug).

• --only BE2/DF_EXR,BE2/DF_HICP_2025 – bestimmte Flüsse neu erstellen.

• --concurrency 5 – parallele DSD-Anfragen.

Ein vollständiger Neuaufbau dauert etwa 80 Sekunden gegen die Live-API. Der Katalogumfang ist auf etwa 9 MB begrenzt, indem Codelisten auf 200 Codes pro Dimension gekürzt werden (einige IWF-Flüsse haben über 65.000+ Codes).

Eine wöchentliche GitHub Action (build-catalog.yml) erstellt den Katalog neu und öffnet einen PR, wenn eine Abweichung festgestellt wird.

Fehlerbehebung

"WAF hat eine HTML-Weiterleitung zurückgegeben"

Die NBB-API befindet sich hinter einer WAF, die für jede Anfrage ohne browserähnlichen User-Agent und einen Origin: https://dataexplorer.nbb.be-Header eine HTML-200-Weiterleitung zurückgibt. Der Client fügt standardmäßig beides ein. Wenn Sie NBB_USER_AGENT überschreiben, behalten Sie eine echt aussehende Browser-Zeichenfolge bei.

"HTTP 404 NoResultsFound" bei einer Datenabfrage

Der SDMX-Schlüssel hat keine Serie gefunden. Verwenden Sie nbb_describe(dataflow_id), um gültige Codes zu sehen, oder übergeben Sie filters={} / key="all", um alles abzurufen und dann über start_period/end_period einzugrenzen.

"Zu viele Beobachtungen, abgeschnitten"

Jede Datenantwort ist standardmäßig auf max_observations=200 begrenzt. Erhöhen Sie den Wert über nbb_query(max_observations=1000) oder grenzen Sie die Abfrage mit einem Zeitfenster ein.

Katalog nicht gefunden

Wenn Sie ohne den gebündelten src/nbb_mcp/data/catalog/ ausführen, führen Sie einmal mcp-nbb-build-catalog aus, um ihn zu befüllen.

Entwicklung

Siehe CONTRIBUTING.md für den vollständigen Entwicklungsablauf. Kurzform:

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 läuft auf Linux, macOS und Windows mit Python 3.11 und 3.12. Siehe DATAFLOWS_CATALOG.md für das klassifizierte Inventar.

Sicherheit

Bitte melden Sie Schwachstellen privat – siehe SECURITY.md.

Lizenz

MIT – siehe LICENSE für den vollständigen Text.

Haftungsausschluss

Dieses Projekt ist nicht mit der National Bank of Belgium verbunden oder von ihr unterstützt. Es ist ein unabhängiger Client ihrer öffentlichen SDMX-REST-API. Die browserähnlichen User-Agent- und Origin-Header werden von der vorgelagerten WAF benötigt und dienen ausschließlich dem Zugriff auf öffentliche statistische Daten. Die Benutzer sind für die Einhaltung der Nutzungsbedingungen der NBB verantwortlich.