> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**

# 🏦 swiss-snb-mcp

![Version](https://img.shields.io/badge/version-0.5.0-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![Data Source](https://img.shields.io/badge/Data-data.snb.ch-red)](https://data.snb.ch)
![CI](https://github.com/malkreide/swiss-snb-mcp/actions/workflows/ci.yml/badge.svg)

> 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](README.de.md)

<p align="center">
  <img src="assets/demo.png" alt="Demo: Claude queries SNB banking statistics via MCP tool call" width="720">
</p>

---

## Overview

`swiss-snb-mcp` connects AI models to the official Swiss National Bank data portal at [data.snb.ch](https://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):**

```bash
uvx swiss-snb-mcp
```

**Via pip:**

```bash
pip install swiss-snb-mcp
```

**From source:**

```bash
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`:**

```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 28 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](EXAMPLES.md) →

---

## 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](https://data.snb.ch) |
| **Terms of Service** | Subject to SNB's [Terms of Use](https://www.snb.ch/en/the-snb/mandates-goals/legal-framework/terms-of-use) and [Copyright](https://www.snb.ch/en/the-snb/mandates-goals/legal-framework/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)
├── 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.

| Era | Revision | Who reaches it |
|---|---|---|
| `initialize` handshake | `2024-11-05` … **`2025-11-25`** | What today's clients speak. The server answers with the revision asked for, or with the `2025-11-25` ceiling when the request asks for something newer. |
| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |

Both revisions are pinned in
[`tests/test_protocol_version.py`](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`](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`](CHANGELOG.md) together.

---

## Testing

```bash
# 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`](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](CHANGELOG.md)

---

## Contributing

See [CONTRIBUTING.md](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](SECURITY.md) for the full security posture, audit results, and how to report a vulnerability.

---

## License

MIT License — see [LICENSE](LICENSE)

---

## Author

Hayal Oezkan · [github.com/malkreide](https://github.com/malkreide)

---

## Credits & Related Projects

- **Data:** [Swiss National Bank](https://data.snb.ch) — SNB data portal (public REST API)
- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic / Linux Foundation
- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) — MCP server for Zurich city open data
- **Related:** [swiss-transport-mcp](https://github.com/malkreide/swiss-transport-mcp) — Swiss public transport MCP server
- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide)

<!-- mcp-name: io.github.malkreide/swiss-snb-mcp -->

<!-- BEGIN GENERATED: install -->
## Installation

Run via [`uv`](https://docs.astral.sh/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`):

```json
{
  "mcpServers": {
    "swiss-snb-mcp": {
      "command": "uvx",
      "args": [
        "swiss-snb-mcp"
      ]
    }
  }
}
```
<!-- END GENERATED: install -->