Swiss Snb MCP Server

🇨🇭 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 the 28 currency series devkum publishes against CHF — including two USD forward rates, which are labelled as such
• 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 23 more series
• 📅 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:

---

Available Tools

Phase 1 — Dedicated Tools

Phase 2 — Generic Cube Tools

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

Resources (static catalogs)

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

Example Use Cases

→ More use cases by audience →

---

Safety & Limits

---

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)
├── 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

---

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

---

MCP Protocol Version

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. This server builds no ASGI app to send an initialize through, so the gate asserts the SDK constants rather than a measured response — the weaker form, named rather than left unsaid.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era — pinning against it alone would leave the era that current clients actually negotiate free to drift.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

---

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"

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

The unit-test payloads are recorded, not invented. Source, retrieval date, selection rule and SHA-256 per file are in tests/fixtures/PROVENANCE.md. A hand-written mock encodes its author's assumption and can therefore never refute it — production code and fixture come from the same head, so where both are wrong, both are wrong together and the suite stays green. Each file keeps every series and only shortens the value lists: the code reasons about the dimensions and merely displays the values, so cutting "the first N series" would have hidden exactly what three of the findings depended on.

---

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

Installation

Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

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