{
  "markdown": "> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**\n\n# 🏦 swiss-snb-mcp\n\n![Version](https://img.shields.io/badge/version-0.4.5-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)\n[![Data Source](https://img.shields.io/badge/Data-data.snb.ch-red)](https://data.snb.ch)\n![CI](https://github.com/malkreide/swiss-snb-mcp/actions/workflows/ci.yml/badge.svg)\n\n> 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.\n\n[🇩🇪 Deutsche Version](README.de.md)\n\n<p align=\"center\">\n  <img src=\"assets/demo.png\" alt=\"Demo: Claude queries SNB banking statistics via MCP tool call\" width=\"720\">\n</p>\n\n---\n\n## Overview\n\n`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.\n\nThe server covers three tiers of datasets, all confirmed against the live API:\n\n**Phase 1 — Dedicated tools:**\n- **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\n- **SNB balance sheet** (Bilanz): gold reserves, foreign exchange investments, banknotes in circulation, sight deposits, and totals\n\n**Phase 2 — Via generic cube tools (`snb_get_cube_data` + `snb_get_cube_metadata`):**\n- **SNB policy rate (Leitzins) and SARON** daily fixing, emergency facility rate, sight deposit rates\n- **SARON compound rates**: Overnight, 1M, 3M, 6M\n- **International money market rates**: SARON (CH), SOFR (USA), TONA (JP), SONIA (UK), €STR/EURIBOR (EZ)\n- **Official central bank rates**: SNB, Fed, ECB, Bank of England, Bank of Japan\n- **Monetary aggregates M1, M2, M3**: stock levels and year-on-year changes\n\n**Phase 3 — Warehouse API (banking statistics) and balance of payments:**\n- **Banking balance sheets** (BSTA BIL): total assets and liabilities by bank group — annual and monthly\n- **Banking income statements** (BSTA EFR): operating income, expenses, taxes by bank group — annual\n- **Balance of payments**: current account, capital account, financial account (quarterly)\n- **International investment position**: components by investment type (quarterly)\n- **Generic warehouse access**: raw access to any SNB Warehouse cube by ID\n\n**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?\"*\n\n---\n\n## Features\n\n- 💱 **Exchange rates** — monthly CHF rates for EUR, USD, JPY, GBP, CNY and 23 more series\n- 📅 **Annual averages** — year-by-year rates from 1980 onwards\n- 🏛️ **SNB balance sheet** — gold, foreign exchange investments, banknotes, sight deposits (monthly)\n- 🔄 **Currency conversion** — convert any amount to CHF using official SNB rates\n- 📈 **Policy rate & SARON** — daily fixing, Leitzins, compound rates (1M/3M/6M)\n- 🌍 **International rate comparison** — SNB, Fed, ECB, Bank of England, Bank of Japan side by side\n- 💰 **Monetary aggregates** — M1, M2, M3 stock levels and year-on-year growth\n- 🏦 **Banking statistics** — balance sheets and income statements by bank group (12 groups)\n- 📊 **Balance of payments** — current account, IIP, and international investment position\n- 🔍 **Generic cube access** — query any SNB data cube or Warehouse cube by ID\n- 🔓 **No authentication required** — fully public SNB data portal\n\n---\n\n## Prerequisites\n\n- Python 3.11+\n- `uv` or `pip`\n- MCP-compatible client (Claude Desktop, Claude Code, or any MCP host)\n\n---\n\n## Installation\n\n**Via uvx (recommended — no permanent installation needed):**\n\n```bash\nuvx swiss-snb-mcp\n```\n\n**Via pip:**\n\n```bash\npip install swiss-snb-mcp\n```\n\n**From source:**\n\n```bash\ngit clone https://github.com/malkreide/swiss-snb-mcp.git\ncd swiss-snb-mcp\npip install -e .\n```\n\n---\n\n## Usage / Quickstart\n\n**Claude Desktop — add to `claude_desktop_config.json`:**\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-snb-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"swiss-snb-mcp\"]\n    }\n  }\n}\n```\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nTry it immediately in Claude Desktop:\n\n> *\"What is the current EUR/CHF exchange rate according to the SNB?\"*\n> *\"Show me the SNB balance sheet for the last 12 months — gold and foreign reserves.\"*\n\n---\n\n## Configuration\n\nNo API key or authentication required. The SNB data portal is fully public.\n\n**Optional environment variable:**\n\n| Variable | Default | Description |\n|---|---|---|\n| `SNB_TIMEOUT` | `15` | HTTP request timeout in seconds |\n\n---\n\n## Available Tools\n\n### Phase 1 — Dedicated Tools\n\n| Tool | Description |\n|---|---|\n| `snb_get_exchange_rates` | Monthly CHF rates for EUR, USD, JPY, GBP, CNY and 22 more currencies |\n| `snb_get_annual_exchange_rates` | Annual average rates, data from 1980 |\n| `snb_get_balance_sheet` | SNB Bilanz positions in millions CHF (monthly) |\n| `snb_convert_currency` | Convert any amount to CHF using official SNB rates |\n\n### Phase 2 — Generic Cube Tools\n\n| Tool | Description |\n|---|---|\n| `snb_get_cube_data` | Generic access to any SNB cube by ID |\n| `snb_get_cube_metadata` | Inspect dimensions and filter values of any cube |\n\n### Phase 3 — Warehouse API (Banking Statistics) and Balance of Payments\n\n| Tool | Description |\n|---|---|\n| `snb_get_banking_balance_sheet` | Banking balance sheets by bank group (monthly/annual, assets/liabilities) |\n| `snb_get_banking_income` | Banking income statements by bank group (annual) |\n| `snb_get_balance_of_payments` | Balance of payments and international investment position (quarterly) |\n| `snb_get_warehouse_data` | Generic access to any SNB Warehouse cube by ID |\n| `snb_get_warehouse_metadata` | Inspect dimensions and last update of a Warehouse cube |\n\n### Resources (static catalogs)\n\nDiscovery aids served as MCP resources rather than tools so they don't crowd the tool manifest:\n\n| URI | Description |\n|---|---|\n| `data://snb/currencies` | All 28 currency IDs with labels and units |\n| `data://snb/balance-sheet-positions` | Asset and liability position IDs |\n| `data://snb/cubes` | All verified Cube-API IDs (Phase 1–2) + discovery guide |\n| `data://snb/warehouse-cubes` | Available Warehouse cube IDs (BSTA) |\n| `data://snb/bank-groups` | All 12 bank group IDs with labels |\n\n### Example Use Cases\n\n| Query | Tool |\n|---|---|\n| *\"What is the current EUR/CHF rate?\"* | `snb_get_exchange_rates` |\n| *\"Convert CHF 10,000 to USD\"* | `snb_convert_currency` |\n| *\"Show SNB gold reserves over the last year\"* | `snb_get_balance_sheet` |\n| *\"What is the current SNB policy rate?\"* | `snb_get_cube_data` (cube: `snbgwdzid`) |\n| *\"How do SNB, Fed and ECB rates compare?\"* | `snb_get_cube_data` (cube: `snboffzisa`) |\n| *\"What is the SARON 3M compound rate?\"* | `snb_get_cube_data` (cube: `zirepo`) |\n| *\"How fast is M3 money supply growing?\"* | `snb_get_cube_data` (cube: `snbmonagg`) |\n| *\"Total assets of all Swiss banks?\"* | `snb_get_banking_balance_sheet` |\n| *\"Income statement of cantonal banks?\"* | `snb_get_banking_income` (bank_group: `G10`) |\n| *\"Switzerland's balance of payments?\"* | `snb_get_balance_of_payments` |\n| *\"Which cubes are available?\"* | resource `data://snb/cubes` |\n\n→ [More use cases by audience](EXAMPLES.md) →\n\n---\n\n## Safety & Limits\n\n| Aspect | Details |\n|--------|---------|\n| **Access** | Read-only (`readOnlyHint: true`) — the server cannot modify or delete any data |\n| **Personal data** | No personal data — all sources are aggregated, public macroeconomic statistics |\n| **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) |\n| **Timeout** | 15 seconds per API call |\n| **Authentication** | No API keys required — both APIs (`/api/cube/` and `/api/warehouse/cube/`) are publicly accessible |\n| **Data source** | [Swiss National Bank — data.snb.ch](https://data.snb.ch) |\n| **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 |\n\n---\n\n## Architecture\n\n```\n┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────┐\n│   Claude / AI   │────▶│     Swiss SNB MCP         │────▶│     data.snb.ch      │\n│   (MCP Host)    │◀────│     (MCP Server)          │◀────│                      │\n└─────────────────┘     │                           │     │  /api/cube/ (JSON)   │\n                        │  11 Tools · 5 Resources   │     │  /api/warehouse/     │\n                        │  Stdio | SSE              │     │  Public · No Auth    │\n                        │                           │     │                      │\n                        │  Phase 1: dedicated tools │     │  Exchange rates      │\n                        │  Phase 2: generic cubes   │     │  Balance sheet       │\n                        │  Phase 3: warehouse +     │     │  Interest rates      │\n                        │           banking stats   │     │  Banking statistics  │\n                        └───────────────────────────┘     │  Balance of payments │\n                                                          └──────────────────────┘\n```\n\n### Cube Discovery Pattern\n\nThe 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.\n\n---\n\n## Project Structure\n\n```\nswiss-snb-mcp/\n├── src/\n│   └── swiss_snb_mcp/\n│       ├── __init__.py\n│       ├── server.py       # Core tools and FastMCP server (Phase 1–2 + BoP)\n│       └── warehouse.py    # Warehouse API tools (Phase 3: banking statistics)\n├── scripts/\n│   └── record_fixtures.py          # records tests/fixtures/* from data.snb.ch\n├── tests/\n│   ├── fixtures/                   # recorded responses + PROVENANCE.md (date, rule, SHA-256)\n│   ├── fixture_data.py             # loader — a missing name is an error, not an empty dict\n│   ├── test_unit.py                # respx-mocked unit tests (run in CI)\n│   ├── test_live_scenarios.py      # 20 live scenarios for Phase 1–2 (nightly)\n│   └── test_live_warehouse.py      # 20 live scenarios for Phase 3 (nightly)\n├── pyproject.toml          # Build configuration (hatchling)\n├── CHANGELOG.md\n├── CONTRIBUTING.md         # Contribution guidelines (English)\n├── CONTRIBUTING.de.md      # German version\n├── SECURITY.md             # Security policy & posture (English)\n├── SECURITY.de.md          # German version\n├── LICENSE\n├── README.md               # This file (English)\n└── README.de.md            # German version\n```\n\n---\n\n## Known Limitations\n\n- **Exchange rates:** Monthly averages only — no intraday or daily rates available via this API\n- **Balance sheet:** Monthly data; some positions may have a publication lag of 1–2 months\n- **Cube access:** Cube IDs are not officially documented by the SNB — read the `data://snb/cubes` resource for verified IDs\n- **Historical depth:** Coverage varies by series; exchange rates go back to 1980, some interest rate series start later\n- **No forecasts:** All data is historical/realised — SNB does not publish forecasts via this API\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `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. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. This server builds no ASGI app to send an `initialize` through, so\nthe gate asserts the SDK constants rather than a measured response — the\nweaker form, named rather than left unsaid.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n---\n\n## Testing\n\n```bash\n# Unit tests (no API key required)\nPYTHONPATH=src pytest tests/ -m \"not live\"\n\n# Integration tests (live SNB API)\nPYTHONPATH=src pytest tests/ -m \"live\"\n\n# Re-record the fixtures from data.snb.ch (writes tests/fixtures/PROVENANCE.md)\npython scripts/record_fixtures.py\n```\n\nThe unit-test payloads are **recorded, not invented**. Source, retrieval date,\nselection rule and SHA-256 per file are in\n[`tests/fixtures/PROVENANCE.md`](tests/fixtures/PROVENANCE.md). A hand-written\nmock encodes its author's assumption and can therefore never refute it —\nproduction code and fixture come from the same head, so where both are wrong,\nboth are wrong together and the suite stays green. Each file keeps **every\nseries** and only shortens the value lists: the code reasons about the\ndimensions and merely displays the values, so cutting \"the first N series\"\nwould have hidden exactly what three of the findings depended on.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting issues, suggesting new SNB cube IDs, and contributing code.\n\n---\n\n## Security\n\nThis 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.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n## Author\n\nHayal Oezkan · [github.com/malkreide](https://github.com/malkreide)\n\n---\n\n## Credits & Related Projects\n\n- **Data:** [Swiss National Bank](https://data.snb.ch) — SNB data portal (public REST API)\n- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic / Linux Foundation\n- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) — MCP server for Zurich city open data\n- **Related:** [swiss-transport-mcp](https://github.com/malkreide/swiss-transport-mcp) — Swiss public transport MCP server\n- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide)\n\n<!-- mcp-name: io.github.malkreide/swiss-snb-mcp -->\n\n<!-- BEGIN GENERATED: install -->\n## Installation\n\nRun 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`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-snb-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"swiss-snb-mcp\"\n      ]\n    }\n  }\n}\n```\n<!-- END GENERATED: install -->\n",
  "bytes": 16090,
  "sha": "adee68752d97f741ee9466206483438a8993a210d2a0a21819d2023973993b02",
  "repo_slug": "malkreide/swiss-snb-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_swiss_snb_mcp_abea9a39/readme"
}