{"id":48924344,"url":"https://github.com/lacausecrypto/mcp-nbb","last_synced_at":"2026-04-17T06:06:49.453Z","repository":{"id":350908841,"uuid":"1208739154","full_name":"lacausecrypto/mcp-nbb","owner":"lacausecrypto","description":"MCP server for the National Bank of Belgium SDMX statistical API — 221 dataflows, 6 tools, 3 resources, bundled enriched catalogue.","archived":false,"fork":false,"pushed_at":"2026-04-12T17:53:10.000Z","size":630,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T19:20:18.738Z","etag":null,"topics":["belgium","mcp","model-context-protocol","national-bank","nbb","sdmx"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mcp-nbb/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lacausecrypto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T17:24:10.000Z","updated_at":"2026-04-12T17:53:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lacausecrypto/mcp-nbb","commit_stats":null,"previous_names":["lacausecrypto/mcp-nbb"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lacausecrypto/mcp-nbb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lacausecrypto%2Fmcp-nbb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lacausecrypto%2Fmcp-nbb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lacausecrypto%2Fmcp-nbb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lacausecrypto%2Fmcp-nbb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lacausecrypto","download_url":"https://codeload.github.com/lacausecrypto/mcp-nbb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lacausecrypto%2Fmcp-nbb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31917372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["belgium","mcp","model-context-protocol","national-bank","nbb","sdmx"],"created_at":"2026-04-17T06:06:48.218Z","updated_at":"2026-04-17T06:06:49.439Z","avatar_url":"https://github.com/lacausecrypto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-nbb\n\n\u003c!-- mcp-name: io.github.lacausecrypto/mcp-nbb --\u003e\n\n[![CI](https://github.com/lacausecrypto/mcp-nbb/actions/workflows/ci.yml/badge.svg)](https://github.com/lacausecrypto/mcp-nbb/actions/workflows/ci.yml)\n[![PyPI version](https://badge.fury.io/py/mcp-nbb.svg)](https://pypi.org/project/mcp-nbb/)\n[![Python versions](https://img.shields.io/pypi/pyversions/mcp-nbb?cacheSeconds=300)](https://pypi.org/project/mcp-nbb/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![MCP compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)\n\n**MCP server for the [National Bank of Belgium](https://www.nbb.be/) SDMX statistical API.**\n\nExposes the 221 NBB dataflows (194 BE2 + 27 IMF/SDDS) as **6 LLM-friendly\ntools** and **3 browsable resources**, with a bundled enriched catalogue so\nthe LLM can discover, describe, and query dataflows without redundant API\ncalls.\n\n- **Upstream**: `https://nsidisseminate-stat.nbb.be/rest` (NSI Web Service v8)\n- **Transport**: stdio (standard MCP)\n- **Python**: 3.11+\n- **Platforms**: Linux, macOS, Windows\n- **221 dataflows** classified into 14 categories — see [DATAFLOWS_CATALOG.md](DATAFLOWS_CATALOG.md)\n\n---\n\n## Install\n\n### From PyPI (recommended)\n\n```bash\n# With uv (runs without installing globally)\nuvx mcp-nbb\n\n# Or install into a regular venv\npip install mcp-nbb\n```\n\n### From source\n\n```bash\ngit clone https://github.com/lacausecrypto/mcp-nbb.git\ncd mcp-nbb\npip install -e .\n```\n\nThe package ships with the full enriched catalogue (~9 MB under\n`src/nbb_mcp/data/catalog/`). No build step is required for regular use.\n\n---\n\n## Claude Desktop configuration\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` on\nmacOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows, or the\nequivalent on Linux.\n\n### Using `uvx` (recommended once published to PyPI)\n\n```json\n{\n  \"mcpServers\": {\n    \"nbb\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nbb\"]\n    }\n  }\n}\n```\n\n### From a local editable install\n\n**macOS / Linux**:\n\n```json\n{\n  \"mcpServers\": {\n    \"nbb\": {\n      \"command\": \"/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb\"\n    }\n  }\n}\n```\n\n**Windows**:\n\n```json\n{\n  \"mcpServers\": {\n    \"nbb\": {\n      \"command\": \"C:\\\\Users\\\\you\\\\projects\\\\mcp-nbb\\\\.venv\\\\Scripts\\\\mcp-nbb.exe\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop — the 6 `nbb_*` tools appear in the MCP panel.\n\n---\n\n## Tools\n\n| Tool | API calls | Purpose |\n|---|---|---|\n| `nbb_search(query, …)` | 0 | Fuzzy search over the 221 local fiches (en/fr/nl/de). |\n| `nbb_describe(dataflow_id, …)` | 0 (default) | Full enriched fiche — dimensions, codelists, key template, common queries. `force_refresh=True` revalidates live. |\n| `nbb_query(dataflow_id, key=…, filters=…)` | 1 | Generic data fetch. Either `key` (raw SDMX) or `filters` (`{\"FREQ\":\"D\",\"EXR_CURRENCY\":\"USD\"}`). |\n| `nbb_quick(topic, …)` | 1 | Topic-based shortcut for 18 common queries — see topic table below. |\n| `nbb_compare(series, …)` | N | Align 2-5 series on a common time index, downsampling finer frequencies via closing aggregation. |\n| `nbb_status()` | 0 | Diagnostic snapshot: catalog, cache, API config. |\n\n### `nbb_quick` topics\n\n| Topic | Dataflow | Parameters |\n|---|---|---|\n| `exchange_rate` | `BE2/DF_EXR` | `currency`, `frequency` |\n| `policy_rate` | `BE2/DF_IRESCB` | — |\n| `mortgage_rate` | `BE2/DF_MIR` | — |\n| `long_term_yield` | `BE2/DF_IROLOYLD` | — |\n| `inflation_hicp` | `BE2/DF_HICP_2025` | — |\n| `inflation_national` | `BE2/DF_NICP_2025` | — |\n| `ppi` | `BE2/DF_PPI` | — |\n| `industrial_production` | `BE2/DF_INDPROD` | — |\n| `gdp` / `gdp_growth` | `BE2/DF_QNA_DISS` | — |\n| `unemployment_rate` | `BE2/DF_UNEMPLOY_RATE` | — |\n| `employment` | `BE2/DF_EMPLOY_DISS` | — |\n| `government_debt` | `BE2/DF_CGD` | — |\n| `government_deficit` | `BE2/DF_NFGOV_NET_DISS` | — |\n| `current_account` | `BE2/DF_BOPBPM6` | — |\n| `consumer_confidence` | `BE2/DF_CONSN` | — |\n| `business_confidence` | `BE2/DF_BUSSURVM` | — |\n| `trade_balance` | `BE2/DF_EXTERNAL_TRADE_OVERVIEW` | — |\n\n### Resources\n\n| URI | Content |\n|---|---|\n| `nbb://catalog` | Markdown index of all 221 dataflows by category. |\n| `nbb://dataflow/{agency}/{dataflow_id}` | Full enriched fiche for one flow. |\n| `nbb://category/{category}` | All flows in a category. |\n\n---\n\n## Example prompts in Claude\n\n\u003e \"What's the EUR/USD exchange rate over the last month?\"\n\u003e → `nbb_quick(\"exchange_rate\", currency=\"USD\", frequency=\"D\", last_n_observations=30)`\n\n\u003e \"Compare Belgian GDP growth to the unemployment rate since 2020.\"\n\u003e → `nbb_compare([{dataflow_id:\"DF_QNA_DISS\",label:\"GDP\"}, {dataflow_id:\"DF_UNEMPLOY_RATE\",label:\"Unemployment\"}], start_period=\"2020-Q1\")`\n\n\u003e \"Find NBB dataflows about consumer credit.\"\n\u003e → `nbb_search(\"consumer credit\")` → `nbb_describe(...)` → `nbb_query(...)`.\n\n---\n\n## Configuration (environment variables)\n\nAll settings have sensible defaults; override via environment variables.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `NBB_API_BASE_URL` | `https://nsidisseminate-stat.nbb.be/rest` | SDMX REST base URL |\n| `NBB_API_TIMEOUT` | `30` | Per-request timeout (s) |\n| `NBB_USER_AGENT` | browser UA | **Required for the WAF** — default is a valid Chrome UA string |\n| `NBB_ORIGIN` | `https://dataexplorer.nbb.be` | **Required for the WAF** |\n| `NBB_HTTP_CACHE_ENABLED` | `true` | Persistent disk cache |\n| `NBB_HTTP_CACHE_PATH` | OS cache dir | Override cache location (defaults to `platformdirs.user_cache_dir`) |\n| `NBB_MEMORY_CACHE_TTL_DATA` | `300` | TTL for data responses (s) |\n| `NBB_MEMORY_CACHE_TTL_STRUCTURE` | `3600` | TTL for structure responses (s) |\n| `NBB_RATE_LIMIT_REQUESTS` | `100` | Self-imposed rate limit (req/period) |\n| `NBB_RATE_LIMIT_PERIOD` | `60` | Rate limit window (s) |\n| `NBB_RETRY_ATTEMPTS` | `3` | Retries on transient errors |\n| `NBB_LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR` |\n| `NBB_LOG_FORMAT` | `json` | `json` or `console` |\n\nThe default cache path resolves to:\n- **Linux**: `~/.cache/mcp-nbb/`\n- **macOS**: `~/Library/Caches/mcp-nbb/`\n- **Windows**: `%LOCALAPPDATA%\\mcp-nbb\\Cache\\`\n\n---\n\n## Refreshing the catalogue\n\nThe bundled `src/nbb_mcp/data/catalog/` snapshot is regenerated by fetching\nthe DSD + codelists for each of the 221 dataflows:\n\n```bash\nmcp-nbb-build-catalog --force\n```\n\nOptions:\n\n- `--force` — rebuild every fiche, ignoring existing ones.\n- `--limit N` — only process the first N flows (debug).\n- `--only BE2/DF_EXR,BE2/DF_HICP_2025` — rebuild specific flows.\n- `--concurrency 5` — parallel DSD requests.\n\nA full rebuild takes ~80 seconds against the live API. Catalogue footprint is\ncapped at ~9 MB by truncating codelists to 200 codes per dimension (some IMF\nflows have 65 000+ codes).\n\nA weekly GitHub Action (`build-catalog.yml`) rebuilds the catalogue and opens\na PR if drift is detected.\n\n---\n\n## Troubleshooting\n\n### \"WAF returned an HTML redirect\"\n\nThe NBB API is behind a WAF that returns an HTML 200 redirect for any request\nwithout a browser-like `User-Agent` and an `Origin: https://dataexplorer.nbb.be`\nheader. The client injects both by default. If you override `NBB_USER_AGENT`,\nkeep a genuine-looking browser string.\n\n### \"HTTP 404 NoResultsFound\" on a data query\n\nThe SDMX key didn't match any series. Use `nbb_describe(dataflow_id)` to see\nvalid codes, or pass `filters={}` / `key=\"all\"` to retrieve everything and\nthen narrow via `start_period`/`end_period`.\n\n### \"Too many observations, truncated\"\n\nEvery data response is capped at `max_observations=200` by default. Increase\nvia `nbb_query(max_observations=1000)` or narrow the query with a period\nwindow.\n\n### Catalogue not found\n\nIf you run without the bundled `src/nbb_mcp/data/catalog/`, run\n`mcp-nbb-build-catalog` once to populate it.\n\n---\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full dev workflow. Short form:\n\n```bash\npip install -e \".[dev]\"\npytest                     # full suite (unit + integration + E2E)\npytest -m \"not e2e\"        # fast subset\nruff check src tests\nmcp-nbb-build-catalog      # refresh the bundled catalogue\nmcp-nbb                    # run the server (stdio)\n```\n\nCI runs on Linux, macOS and Windows with Python 3.11 and 3.12. See\n[DATAFLOWS_CATALOG.md](DATAFLOWS_CATALOG.md) for the classified inventory.\n\n---\n\n## Security\n\nPlease report vulnerabilities privately — see [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) — see `LICENSE` for the full text.\n\n## Disclaimer\n\nThis project is **not affiliated with or endorsed by** the National Bank of\nBelgium. It is an independent client of their public SDMX REST API. The\nbrowser-like `User-Agent` and `Origin` headers are required by the upstream\nWAF and used solely to access public statistical data. Users are responsible\nfor complying with NBB's terms of use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flacausecrypto%2Fmcp-nbb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flacausecrypto%2Fmcp-nbb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flacausecrypto%2Fmcp-nbb/lists"}