mcp-nbb

MCP 服务器，用于 National Bank of Belgium 的 SDMX 统计 API。

将 221 个 NBB 数据流（194 个 BE2 + 27 个 IMF/SDDS）暴露为 6 个 LLM 友好工具 和 3 个可浏览资源，并附带一个丰富的目录，使 LLM 无需冗余的 API 调用即可发现、描述和查询数据流。

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

• 传输: stdio (标准 MCP)

• Python: 3.11+

• 平台: Linux, macOS, Windows

• 221 个数据流，分为 14 个类别 — 参见 DATAFLOWS_CATALOG.md

安装

从 PyPI 安装（推荐）

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

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

从源码安装

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

该包附带完整的丰富目录（约 9 MB，位于 src/nbb_mcp/data/catalog/ 下）。常规使用无需构建步骤。

Related MCP server: OECD MCP Server

Claude Desktop 配置

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json，或在 Linux 上编辑等效文件。

使用 uvx（推荐，一旦发布到 PyPI）

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

从本地可编辑安装

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

重启 Claude Desktop — 6 个 nbb_* 工具将出现在 MCP 面板中。

工具

nbb_quick 主题

资源

Claude 中的示例提示

"上个月 EUR/USD 汇率是多少？" → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

"比较自 2020 年以来比利时 GDP 增长与失业率。" → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

"查找有关消费信贷的 NBB 数据流。" → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...)。

配置（环境变量）

所有设置都有合理的默认值；可通过环境变量覆盖。

默认缓存路径解析为：

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

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

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

刷新目录

捆绑的 src/nbb_mcp/data/catalog/ 快照通过获取 221 个数据流中的每一个的 DSD + 代码表来重新生成：

mcp-nbb-build-catalog --force

选项：

• --force — 重建每个条目，忽略现有条目。

• --limit N — 仅处理前 N 个数据流（调试）。

• --only BE2/DF_EXR,BE2/DF_HICP_2025 — 重建特定数据流。

• --concurrency 5 — 并行 DSD 请求。

针对实时 API 的完整重建大约需要 80 秒。目录占用空间限制在约 9 MB，方法是将每个维度的代码表截断为 200 个代码（某些 IMF 数据流有 65 000+ 个代码）。

每周的 GitHub Action（build-catalog.yml）会重建目录，并在检测到漂移时打开 PR。

故障排除

“WAF 返回了 HTML 重定向”

NBB API 位于 WAF 之后，对于任何没有类似浏览器的 User-Agent 和 Origin: https://dataexplorer.nbb.be 头的请求，WAF 都会返回 HTML 200 重定向。客户端默认注入这两者。如果您覆盖 NBB_USER_AGENT，请保留一个看起来真实的浏览器字符串。

数据查询时出现“HTTP 404 NoResultsFound”

SDMX 键未匹配任何序列。使用 nbb_describe(dataflow_id) 查看有效代码，或传递 filters={} / key="all" 以检索所有内容，然后通过 start_period/end_period 缩小范围。

“观测值过多，已截断”

默认情况下，每个数据响应限制为 max_observations=200。可通过 nbb_query(max_observations=1000) 增加，或使用时间段窗口缩小查询范围。

未找到目录

如果您在没有捆绑的 src/nbb_mcp/data/catalog/ 的情况下运行，请运行一次 mcp-nbb-build-catalog 来填充它。

开发

完整开发工作流程请参见 CONTRIBUTING.md。简而言之：

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 在 Linux、macOS 和 Windows 上使用 Python 3.11 和 3.12 运行。分类清单请参见 DATAFLOWS_CATALOG.md。

安全

请私下报告漏洞 — 参见 SECURITY.md。

许可证

MIT — 完整文本请参见 LICENSE。

免责声明

本项目与比利时国家银行无关联，也未获得其认可。它是其公共 SDMX REST API 的独立客户端。类似浏览器的 User-Agent 和 Origin 头是上游 WAF 所要求的，仅用于访问公共统计数据。用户有责任遵守 NBB 的使用条款。