swiss-snb-mcp 0.4.3

MCP server for Swiss National Bank (SNB) data portal — exchange rates, balance sheet, and monetary statistics

🇨🇭 Part of the Swiss Public Data MCP Portfolio

🏦 swiss-snb-mcp

MCP server for the Swiss National Bank (SNB) data portal — exchange rates, balance sheet, interest rates, SARON, monetary aggregates, banking statistics, and balance of payments.

🇩🇪 Deutsche Version

---

Overview

swiss-snb-mcp connects AI models to the official Swiss National Bank data portal at data.snb.ch via the Model Context Protocol (MCP). It provides structured access to SNB's public REST API — no authentication required.

The server covers three tiers of datasets, all confirmed against the live API:

Phase 1 — Dedicated tools:

• Exchange rates (monthly averages, month-end rates, annual averages) for 27 currencies against CHF
• SNB balance sheet (Bilanz): gold reserves, foreign exchange investments, banknotes in circulation, sight deposits, and totals

Phase 2 — Via generic cube tools (snb_get_cube_data + snb_get_cube_metadata):

• SNB policy rate (Leitzins) and SARON daily fixing, emergency facility rate, sight deposit rates
• SARON compound rates: Overnight, 1M, 3M, 6M
• International money market rates: SARON (CH), SOFR (USA), TONA (JP), SONIA (UK), €STR/EURIBOR (EZ)
• Official central bank rates: SNB, Fed, ECB, Bank of England, Bank of Japan
• Monetary aggregates M1, M2, M3: stock levels and year-on-year changes

Phase 3 — Warehouse API (banking statistics) and balance of payments:

• Banking balance sheets (BSTA BIL): total assets and liabilities by bank group — annual and monthly
• Banking income statements (BSTA EFR): operating income, expenses, taxes by bank group — annual
• Balance of payments: current account, capital account, financial account (quarterly)
• International investment position: components by investment type (quarterly)
• Generic warehouse access: raw access to any SNB Warehouse cube by ID

Anchor demo query: "What was the EUR/CHF exchange rate during the 2015 Franc shock, and where does the SNB policy rate stand today compared to the Fed and ECB?"

---

Features

• 💱 Exchange rates — monthly CHF rates for EUR, USD, JPY, GBP, CNY and 22 more currencies
• 📅 Annual averages — year-by-year rates from 1980 onwards
• 🏛️ SNB balance sheet — gold, foreign exchange investments, banknotes, sight deposits (monthly)
• 🔄 Currency conversion — convert any amount to CHF using official SNB rates
• 📈 Policy rate & SARON — daily fixing, Leitzins, compound rates (1M/3M/6M)
• 🌍 International rate comparison — SNB, Fed, ECB, Bank of England, Bank of Japan side by side
• 💰 Monetary aggregates — M1, M2, M3 stock levels and year-on-year growth
• 🏦 Banking statistics — balance sheets and income statements by bank group (12 groups)
• 📊 Balance of payments — current account, IIP, and international investment position
• 🔍 Generic cube access — query any SNB data cube or Warehouse cube by ID
• 🔓 No authentication required — fully public SNB data portal

---

Prerequisites

• Python 3.11+
• uv or pip
• MCP-compatible client (Claude Desktop, Claude Code, or any MCP host)

---

Installation

Via uvx (recommended — no permanent installation needed):

uvx swiss-snb-mcp

Via pip:

pip install swiss-snb-mcp

From source:

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

---

Usage / Quickstart

Claude Desktop — add to claude_desktop_config.json:

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

Config file locations:

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

Try it immediately in Claude Desktop:

"What is the current EUR/CHF exchange rate according to the SNB?" "Show me the SNB balance sheet for the last 12 months — gold and foreign reserves."

---

Configuration

No API key or authentication required. The SNB data portal is fully public.

Optional environment variable:

Variable	Default	Description
SNB_TIMEOUT	15	HTTP request timeout in seconds

---

Available Tools

Phase 1 — Dedicated Tools

Tool	Description
snb_get_exchange_rates	Monthly CHF rates for EUR, USD, JPY, GBP, CNY and 22 more currencies
snb_get_annual_exchange_rates	Annual average rates, data from 1980
snb_get_balance_sheet	SNB Bilanz positions in millions CHF (monthly)
snb_convert_currency	Convert any amount to CHF using official SNB rates

Phase 2 — Generic Cube Tools

Tool	Description
snb_get_cube_data	Generic access to any SNB cube by ID
snb_get_cube_metadata	Inspect dimensions and filter values of any cube

Phase 3 — Warehouse API (Banking Statistics) and Balance of Payments

Tool	Description
snb_get_banking_balance_sheet	Banking balance sheets by bank group (monthly/annual, assets/liabilities)
snb_get_banking_income	Banking income statements by bank group (annual)
snb_get_balance_of_payments	Balance of payments and international investment position (quarterly)
snb_get_warehouse_data	Generic access to any SNB Warehouse cube by ID
snb_get_warehouse_metadata	Inspect dimensions and last update of a Warehouse cube

Resources (static catalogs)

Discovery aids served as MCP resources rather than tools so they don't crowd the tool manifest:

URI	Description
data://snb/currencies	All 27 currency IDs with labels and units
data://snb/balance-sheet-positions	Asset and liability position IDs
data://snb/cubes	All verified Cube-API IDs (Phase 1–2) + discovery guide
data://snb/warehouse-cubes	Available Warehouse cube IDs (BSTA)
data://snb/bank-groups	All 12 bank group IDs with labels

Example Use Cases

Query	Tool
"What is the current EUR/CHF rate?"	snb_get_exchange_rates
"Convert CHF 10,000 to USD"	snb_convert_currency
"Show SNB gold reserves over the last year"	snb_get_balance_sheet
"What is the current SNB policy rate?"	snb_get_cube_data (cube: snbgwdzid)
"How do SNB, Fed and ECB rates compare?"	snb_get_cube_data (cube: snboffzisa)
"What is the SARON 3M compound rate?"	snb_get_cube_data (cube: zirepo)
"How fast is M3 money supply growing?"	snb_get_cube_data (cube: snbmonagg)
"Total assets of all Swiss banks?"	snb_get_banking_balance_sheet
"Income statement of cantonal banks?"	snb_get_banking_income (bank_group: G10)
"Switzerland's balance of payments?"	snb_get_balance_of_payments
"Which cubes are available?"	resource data://snb/cubes

→ More use cases by audience →

---

Safety & Limits

Aspect	Details
Access	Read-only (readOnlyHint: true) — the server cannot modify or delete any data
Personal data	No personal data — all sources are aggregated, public macroeconomic statistics
Rate limits	SNB Warehouse API has WAF protection (HTTP 503 after ~100 rapid requests); the server retries automatically with exponential backoff (max 3 retries, delays 2/4/8s)
Timeout	15 seconds per API call
Authentication	No API keys required — both APIs (/api/cube/ and /api/warehouse/cube/) are publicly accessible
Data source	Swiss National Bank — data.snb.ch
Terms of Service	Subject to SNB's Terms of Use and Copyright; data is free for non-commercial use with source attribution

---

Architecture

┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────┐
│   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 Discovery Pattern

The SNB API follows a consistent cube-based structure. Read the data://snb/cubes resource to explore verified cube IDs, then snb_get_cube_metadata to inspect dimensions before querying with snb_get_cube_data. Phase 3 adds the Warehouse API (/api/warehouse/cube/) for granular banking statistics — start from the data://snb/warehouse-cubes and data://snb/bank-groups resources.

---

Project Structure

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)
├── tests/
│   ├── 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

---

Known Limitations

• Exchange rates: Monthly averages only — no intraday or daily rates available via this API
• Balance sheet: Monthly data; some positions may have a publication lag of 1–2 months
• Cube access: Cube IDs are not officially documented by the SNB — read the data://snb/cubes resource for verified IDs
• Historical depth: Coverage varies by series; exchange rates go back to 1980, some interest rate series start later
• No forecasts: All data is historical/realised — SNB does not publish forecasts via this API

---

Testing

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

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

---

Changelog

See CHANGELOG.md

---

Contributing

See CONTRIBUTING.md for guidelines on reporting issues, suggesting new SNB cube IDs, and contributing code.

---

Security

This server is read-only, processes no personal data, and talks only to data.snb.ch. See SECURITY.md for the full security posture, audit results, and how to report a vulnerability.

---

License

MIT License — see LICENSE

---

Author

Hayal Oezkan · github.com/malkreide

---

Credits & Related Projects

• Data: Swiss National Bank — SNB data portal (public REST API)
• Protocol: Model Context Protocol — Anthropic / Linux Foundation
• Related: zurich-opendata-mcp — MCP server for Zurich city open data
• Related: swiss-transport-mcp — Swiss public transport MCP server
• Portfolio: Swiss Public Data MCP Portfolio