swiss-snb-mcp

🇨🇭 属于 Swiss Public Data MCP Portfolio

🏦 swiss-snb-mcp

用于访问瑞士国家银行（SNB）数据门户的 MCP 服务——提供汇率、资产负债表、利率、SARON、货币总量、银行统计数据和国际收支数据。

🇩🇪 德语版

---

概览

swiss-snb-mcp 通过模型上下文协议（MCP），将 AI 模型连接到瑞士国家银行的官方数据门户 data.snb.ch。它提供对 SNB 公共 REST API 的结构化访问——无需身份验证。

该服务涵盖三个层级的数据集，且均已通过实时 API 确认：

阶段 1 — 专用工具：

• 汇率（月平均汇率、月末汇率、年平均汇率）：覆盖 devkum 发布的 28 种兑 CHF 货币序列，包括两种明确标注的 USD 远期汇率
• SNB 资产负债表（Bilanz）：黄金储备、外汇投资、流通钞票、活期存款及合计数

阶段 2 — 通过通用数据立方体工具（snb_get_cube_data + snb_get_cube_metadata）访问：

• SNB 政策利率（Leitzins）和 SARON：每日定盘利率、紧急贷款工具利率、活期存款利率
• SARON 复合利率：隔夜、1M、3M、6M
• 国际货币市场利率：SARON（CH）、SOFR（USA）、TONA（JP）、SONIA（UK）、€STR/EURIBOR（EZ）
• 官方央行利率：SNB、美联储、ECB、英格兰银行、日本银行
• 货币总量 M1、M2、M3：存量水平和同比变化

阶段 3 — Warehouse API（银行统计数据）和国际收支：

• 银行资产负债表（BSTA BIL）：按银行类别统计的资产和负债总额——年度和月度数据
• 银行损益表（BSTA EFR）：按银行类别统计的营业收入、支出和税项——年度数据
• 国际收支：经常账户、资本账户、金融账户（季度数据）
• 国际投资头寸：按投资类型划分的组成项目（季度数据）
• 通用 Warehouse 访问：按 ID 原始访问任意 SNB Warehouse 数据立方体

演示核心问题： “2015 年瑞郎冲击期间，欧元兑瑞郎汇率是多少？与美联储和 ECB 相比，SNB 当前的政策利率处于什么水平？”

---

功能

• 💱 汇率 — EUR、USD、JPY、GBP、CNY 等 23 种以上货币兑 CHF 的月度汇率
• 📅 年度平均汇率 — 从 1980 年起逐年的汇率
• 🏛️ SNB 资产负债表 — 黄金、外汇投资、钞票、活期存款（月度数据）
• 🔄 货币兑换 — 使用 SNB 官方汇率将任意金额兑换为 CHF
• 📈 政策利率和 SARON — 每日定盘利率、Leitzins、复合利率（1M/3M/6M）
• 🌍 国际利率对比 — 并列比较 SNB、美联储、ECB、英格兰银行和日本银行
• 💰 货币总量 — M1、M2、M3 存量水平和同比增长
• 🏦 银行统计数据 — 按银行类别统计的资产负债表和损益表（12 类）
• 📊 国际收支 — 经常账户、IIP 和国际投资头寸
• 🔍 通用数据立方体访问 — 按 ID 查询任意 SNB 数据立方体或 Warehouse 数据立方体
• 🔓 无需身份验证 — 完全开放的 SNB 数据门户

---

前置条件

• Python 3.11+
• uv 或 pip
• 兼容 MCP 的客户端（Claude Desktop、Claude Code 或任何 MCP 宿主）

---

安装

通过 uvx（推荐 — 无需永久安装）：

uvx swiss-snb-mcp

通过 pip：

pip install swiss-snb-mcp

从源码安装：

git clone https://github.com/malkreide/swiss-snb-mcp.git
cd swiss-snb-mcp
pip install -e .

---

使用 / 快速入门

Claude Desktop — 添加到 claude_desktop_config.json：

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

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

在 Claude Desktop 中立即试用：

“根据 SNB 的数据，当前 EUR/CHF 汇率是多少？” “显示过去 12 个月的 SNB 资产负债表 — 黄金和外汇储备。”

---

配置

无需 API 密钥或身份验证。SNB 数据门户完全公开。

可选环境变量：

变量	默认值	描述
SNB_TIMEOUT	15	HTTP 请求超时时间，单位为秒

---

可用工具

阶段 1 — 专用工具

工具	描述
snb_get_exchange_rates	EUR、USD、JPY、GBP、CNY 及另外 22 种货币的月度 CHF 汇率
snb_get_annual_exchange_rates	年平均汇率，数据始于 1980 年
snb_get_balance_sheet	SNB 资产负债表项目，单位为百万 CHF（月度）
snb_convert_currency	使用 SNB 官方汇率将任意金额兑换为 CHF

阶段 2 — 通用 Cube 工具

工具	描述
snb_get_cube_data	通过 ID 通用访问任意 SNB Cube
snb_get_cube_metadata	查看任意 Cube 的维度和筛选值

阶段 3 — Warehouse API（银行业统计）和国际收支

工具	描述
snb_get_banking_balance_sheet	按银行集团划分的银行资产负债表（月度/年度，资产/负债）
snb_get_banking_income	按银行集团划分的银行损益表（年度）
snb_get_balance_of_payments	国际收支和国际投资头寸（季度）
snb_get_warehouse_data	通过 ID 通用访问任意 SNB Warehouse Cube
snb_get_warehouse_metadata	查看 Warehouse Cube 的维度和最后更新时间

资源（静态目录）

用于发现的辅助信息以 MCP 资源而非工具的形式提供，避免工具清单过于臃肿：

URI	描述
data://snb/currencies	全部 28 种货币的 ID、标签和单位
data://snb/balance-sheet-positions	资产和负债项目 ID
data://snb/cubes	所有已验证的 Cube-API ID（阶段 1–2）+ 发现指南
data://snb/warehouse-cubes	可用的 Warehouse Cube ID（BSTA）
data://snb/bank-groups	全部 12 个银行集团的 ID 和标签

示例用例

查询	工具
“当前 EUR/CHF 汇率是多少？”	snb_get_exchange_rates
“将 CHF 10,000 兑换为 USD”	snb_convert_currency
“显示过去一年 SNB 的黄金储备”	snb_get_balance_sheet
“当前 SNB 政策利率是多少？”	snb_get_cube_data（Cube：snbgwdzid）
“SNB、Fed 和 ECB 的利率如何比较？”	snb_get_cube_data（Cube：snboffzisa）
“SARON 3M 复合利率是多少？”	snb_get_cube_data（Cube：zirepo）
“M3 货币供应量增长有多快？”	snb_get_cube_data（Cube：snbmonagg）
“所有瑞士银行的总资产是多少？”	snb_get_banking_balance_sheet
“州立银行的损益表是什么样的？”	snb_get_banking_income（bank_group：G10）
“瑞士的国际收支情况如何？”	snb_get_balance_of_payments
“有哪些可用的 Cube？”	资源 data://snb/cubes

→ 按受众查看更多用例 →

---

安全性与限制

方面	详情
访问权限	只读（readOnlyHint: true）——服务无法修改或删除任何数据
个人数据	不含个人数据——所有来源均为汇总的公开宏观经济统计数据
速率限制	SNB Warehouse API 受到 WAF 保护（快速请求约 100 次后返回 HTTP 503）；服务会自动采用指数退避策略重试（最多重试 3 次，延迟分别为 2/4/8s）
超时	每次 API 调用 15 秒
身份验证	无需 API 密钥——两个 API（/api/cube/ 和 /api/warehouse/cube/）均可公开访问
数据源	瑞士国家银行 — data.snb.ch
服务条款	受 SNB 的使用条款和版权声明约束；数据可免费用于非商业用途，但须注明来源

---

架构

┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────┐
│   Claude / AI   │────▶│     Swiss SNB MCP         │────▶│     data.snb.ch      │
│   (MCP Host)    │◀────│     (MCP Server)          │◀────│                      │
└─────────────────┘     │                           │     │  /api/cube/ (JSON)   │
                        │  11 Tools · 5 Resources   │     │  /api/warehouse/     │
                        │  Stdio | SSE              │     │  Public · No Auth    │
                        │                           │     │                      │
                        │  Phase 1: dedicated tools │     │  Exchange rates      │
                        │  Phase 2: generic cubes   │     │  Balance sheet       │
                        │  Phase 3: warehouse +     │     │  Interest rates      │
                        │           banking stats   │     │  Banking statistics  │
                        └───────────────────────────┘     │  Balance of payments │
                                                          └──────────────────────┘

Cube 发现模式

SNB API 遵循一致的基于 cube 的结构。读取 data://snb/cubes 资源以查看经过验证的 cube ID，然后使用 snb_get_cube_metadata 检查维度，再通过 snb_get_cube_data 查询数据。第 3 阶段新增了 Warehouse API（/api/warehouse/cube/），用于获取粒度更细的银行统计数据——请从 data://snb/warehouse-cubes 和 data://snb/bank-groups 资源开始。

---

项目结构

swiss-snb-mcp/
├── src/
│   └── swiss_snb_mcp/
│       ├── __init__.py
│       ├── server.py       # Core tools and FastMCP server (Phase 1–2 + BoP)
│       └── warehouse.py    # Warehouse API tools (Phase 3: banking statistics)
├── scripts/
│   └── record_fixtures.py          # records tests/fixtures/* from data.snb.ch
├── tests/
│   ├── fixtures/                   # recorded responses + PROVENANCE.md (date, rule, SHA-256)
│   ├── fixture_data.py             # loader — a missing name is an error, not an empty dict
│   ├── test_unit.py                # respx-mocked unit tests (run in CI)
│   ├── test_live_scenarios.py      # 20 live scenarios for Phase 1–2 (nightly)
│   └── test_live_warehouse.py      # 20 live scenarios for Phase 3 (nightly)
├── pyproject.toml          # Build configuration (hatchling)
├── CHANGELOG.md
├── CONTRIBUTING.md         # Contribution guidelines (English)
├── CONTRIBUTING.de.md      # German version
├── SECURITY.md             # Security policy & posture (English)
├── SECURITY.de.md          # German version
├── LICENSE
├── README.md               # This file (English)
└── README.de.md            # German version

---

已知限制

• 汇率： 仅提供月平均值——此 API 不提供日内或每日汇率
• 资产负债表： 提供月度数据；部分项目的发布时间可能延迟 1–2 个月
• Cube 访问： SNB 未正式记录 cube ID——请读取 data://snb/cubes 资源以查看经过验证的 ID
• 历史跨度： 覆盖范围因序列而异；汇率数据可追溯至 1980 年，部分利率序列的起始时间较晚
• 无预测： 所有数据均为历史数据或已实现数据——SNB 不通过此 API 发布预测数据

---

MCP 协议版本

此服务在同一端点上支持两个协议时代。客户端在连接上的第一个请求决定使用哪一个；之后若声明属于另一个时代，则会被拒绝。

时代	修订版	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的协议。服务会以请求指定的修订版作答；若请求的是更新的版本，则以 2025-11-25 上限作答。
每请求封装	2026-07-28	携带 2026-07-28 _meta 封装的请求会开启现代连接。

两个修订版都固定在 tests/test_protocol_version.py 中，并与已安装的 SDK 进行断言，因此 Dependabot 对 mcp 的升级不会悄然改变其中任何一个。

上表中的内容是实测结果，而非推断。同一个门控会驱动服务的真实服务循环，该循环通过内存流对运行——生产环境中的 stdio 循环也是如此——并向其中发送实际的 JSON-RPC 帧：封装请求由 2026-07-28 版本提供服务；请求 initialize 使用 2026-07-28 时，响应为 2025-11-25；在已确定版本的连接上，来自另一个时代的声明会被拒绝（一种方向返回 -32022，另一种方向返回 -32600）。本节的早期版本曾声称测量需要 ASGI 应用；其实并不需要——现代时代没有 initialize，而且握手从一开始就不是通过 HTTP 进行的。

服务对自身信息的报告也以同样方式实测，见 tests/test_server_identity.py：软件包版本和项目 URL 是从线上读取的，而不是从构造函数中读取的。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——只针对它固定版本，会导致当前客户端实际协商的时代仍可悄然变化。

更新策略。 门控测试失败时，不要盲目修改常量：阅读两个修订版之间的规范变更日志，确认服务仍按预期运行，然后同时更新常量、本节、README.de.md 和 CHANGELOG.md。

---

测试

# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (live SNB API)
PYTHONPATH=src pytest tests/ -m "live"

# Re-record the fixtures from data.snb.ch (writes tests/fixtures/PROVENANCE.md)
python scripts/record_fixtures.py

单元测试负载是记录所得，而非凭空编造。每个文件的来源、检索日期、选择规则和 SHA-256 值均列于 tests/fixtures/PROVENANCE.md。手写模拟数据编码了作者的假设，因此永远无法证伪这些假设——生产代码和测试夹具来自同一版本，因此如果两者都错，它们也会一起出错，测试套件仍会通过。每个文件都保留所有序列，只缩短数值列表：代码会处理维度，而只展示数值，因此若截取“前 N 个序列”，就会恰好掩盖三个发现所依赖的内容。

---

更新日志

参见 CHANGELOG.md

---

贡献

有关问题报告、建议新的 SNB 立方体 ID 以及贡献代码的指南，请参阅 CONTRIBUTING.md。

---

安全

此服务为只读服务，不处理个人数据，并且只与 data.snb.ch 通信。有关完整的安全状况、审计结果以及漏洞报告方式，请参阅 SECURITY.md。

---

许可证

MIT 许可证 — 参见 LICENSE

---

作者

Hayal Oezkan · github.com/malkreide

---

致谢与相关项目

• 数据： Swiss National Bank — SNB 数据门户（公共 REST API）
• 协议： Model Context Protocol — Anthropic / Linux Foundation
• 相关项目： zurich-opendata-mcp — 用于苏黎世市开放数据的 MCP 服务
• 相关项目： swiss-transport-mcp — 瑞士公共交通 MCP 服务
• 作品集： Swiss Public Data MCP Portfolio

安装

通过 uv 的 uvx 运行，无需克隆或手动安装。将其添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

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