Swiss Snb Mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio

🏦 swiss-snb-mcp

[Version] [License: MIT] [Python 3.11+] [MCP] [Data Source] [CI]

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

[Demo: Claude queries SNB banking statistics via MCP tool call]

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.gitcd swiss-snb-mcppip 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.

The table above is measured, not inferred. The same gate drives the server's real serving loop over an in-memory stream pair — the loop stdio runs in production — and sends actual JSON-RPC frames through it: an enveloped request is served at 2026-07-28, an initialize asking for 2026-07-28 is answered 2025-11-25, and a claim from the other era is refused on an already-decided connection (-32022 one way, -32600 the other). An earlier revision of this section claimed the measurement needed an ASGI app; it does not — the modern era has no initialize, and the handshake never rode on HTTP to begin with.

What the server reports about itself is measured the same way, in tests/test_server_identity.py: the package version and the project URL are read back off the wire, not off the constructor.

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