mcp-nbb

mcp-nbb

用于比利时国家银行 SDMX 统计 API 的 MCP 服务。

将 NBB 的 221 个数据流（194 个 BE2 + 27 个 IMF/SDDS）作为 6 个适合大模型使用的工具和 3 个可浏览的资源提供，并附带一个增强版目录，让大模型无需重复调用 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 .

软件包附带完整的增强版目录（src/nbb_mcp/data/catalog/ 下约 9 MB）。常规使用无需构建。

---

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 — MCP 面板中将显示 6 个 nbb_* 工具。

---

工具

工具	API 调用次数	用途
nbb_search(query, …)	0	在本地 221 个数据说明卡中进行模糊搜索（en/fr/nl/de）。
nbb_describe(dataflow_id, …)	0（默认）	完整的增强版数据说明卡 — 维度、代码列表、键模板、常见查询。force_refresh=True 可重新验证实时数据。
nbb_query(dataflow_id, key=…, filters=…)	1	通用数据获取。使用 key（原始 SDMX）或 filters（{"FREQ":"D","EXR_CURRENCY":"USD"}）。
nbb_quick(topic, …)	1	针对 18 个常见查询的主题快捷方式 — 请参阅下方主题表。
nbb_compare(series, …)	N	将 2-5 个序列按共同时间索引对齐，通过收盘聚合对更高频率的数据进行降采样。
nbb_status()	0	诊断快照：目录、缓存、API 配置。

nbb_quick 主题

主题	数据流	参数
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	—
trade_balance	BE2/DF_EXTERNAL_TRADE_OVERVIEW	—

资源

URI	内容
nbb://catalog	按类别列出全部 221 个数据流的 Markdown 索引。
nbb://dataflow/{agency}/{dataflow_id}	单个数据流的完整增强版数据说明卡。
nbb://category/{category}	某个类别中的所有数据流。

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(...)。

---

配置（环境变量）

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

变量	默认值	用途
NBB_API_BASE_URL	https://nsidisseminate-stat.nbb.be/rest	SDMX REST 基础 URL
NBB_API_TIMEOUT	30	每次请求的超时时间（秒）
NBB_USER_AGENT	browser UA	WAF 必需 — 默认值为有效的 Chrome UA 字符串
NBB_ORIGIN	https://dataexplorer.nbb.be	WAF 必需
NBB_HTTP_CACHE_ENABLED	true	持久化磁盘缓存
NBB_HTTP_CACHE_PATH	OS cache dir	覆盖缓存位置（默认使用 platformdirs.user_cache_dir）
NBB_MEMORY_CACHE_TTL_DATA	300	数据响应的 TTL（秒）
NBB_MEMORY_CACHE_TTL_STRUCTURE	3600	结构响应的 TTL（秒）
NBB_RATE_LIMIT_REQUESTS	100	自行设定的速率限制（每个周期的请求数）
NBB_RATE_LIMIT_PERIOD	60	速率限制窗口（秒）
NBB_RETRY_ATTEMPTS	3	遇到临时错误时的重试次数
NBB_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR
NBB_LOG_FORMAT	json	json 或 console

默认缓存路径为：

• 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 — 重建每个 fiche，忽略已有内容。
• --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 的独立客户端。上游 WAF 要求使用类似浏览器的 User-Agent 和 Origin 标头，这些标头仅用于访问公开统计数据。用户有责任遵守 NBB 的使用条款。