swiss-snb-mcp

🇨🇭 スイス公共データ MCP ポートフォリオの一部

🏦 swiss-snb-mcp

スイス国立銀行（SNB）のデータポータル向け MCP サーバーです。為替レート、貸借対照表、金利、SARON、通貨供給量、銀行統計、国際収支を扱います。

🇩🇪 ドイツ語版

---

概要

swiss-snb-mcp は、Model Context Protocol（MCP）を介して、AI モデルを data.snb.ch のスイス国立銀行公式データポータルに接続します。認証不要で、SNB の公開 REST API に構造化されたアクセスを提供します。

このサーバーは、ライブ API で確認済みの3層のデータセットを扱います。

フェーズ 1 — 専用ツール：

• 為替レート（月平均、月末レート、年平均）：devkum が CHF に対して公表する28通貨系列を対象とします。USD の先物レート2種類も、先物レートとして明記して含みます
• SNB の貸借対照表（Bilanz）：金準備、外貨投資、流通紙幣、要求払預金、合計

フェーズ 2 — 汎用キューブツール経由（snb_get_cube_data + snb_get_cube_metadata）：

• SNB 政策金利（Leitzins）と SARONの日次フィキシング、緊急融資制度金利、要求払預金金利
• SARON 複利金利：翌日物、1M、3M、6M
• 国際金融市場金利：SARON（スイス）、SOFR（米国）、TONA（日本）、SONIA（英国）、€STR/EURIBOR（ユーロ圏）
• 各国中央銀行の公式金利：SNB、Fed、ECB、イングランド銀行、日本銀行
• 通貨供給量 M1、M2、M3：残高水準と前年同期比の変化

フェーズ 3 — ウェアハウス API（銀行統計）と国際収支：

• 銀行の貸借対照表（BSTA BIL）：銀行グループ別の総資産と負債 — 年次および月次
• 銀行の損益計算書（BSTA EFR）：銀行グループ別の営業収益、費用、税金 — 年次
• 国際収支：経常収支、資本勘定、金融勘定（四半期）
• 国際投資ポジション：投資種類別の内訳（四半期）
• 汎用ウェアハウスアクセス：ID を指定して、任意の SNB ウェアハウスキューブの生データにアクセス

デモの中心となるクエリ： 「2015年のフランショック時の EUR/CHF 為替レートはいくらで、現在の SNB 政策金利は Fed や ECB と比べてどの水準ですか？」

---

機能

• 💱 為替レート — EUR、USD、JPY、GBP、CNY など23系列以上の CHF 月次レート
• 📅 年平均 — 1980年以降の年ごとのレート
• 🏛️ SNB の貸借対照表 — 金、外貨投資、紙幣、要求払預金（月次）
• 🔄 通貨換算 — SNB の公式レートを使用して任意の金額を CHF に換算
• 📈 政策金利と SARON — 日次フィキシング、Leitzins、複利金利（1M/3M/6M）
• 🌍 国際金利の比較 — SNB、Fed、ECB、イングランド銀行、日本銀行を並べて比較
• 💰 通貨供給量 — M1、M2、M3 の残高水準と前年同期比の伸び率
• 🏦 銀行統計 — 銀行グループ別の貸借対照表と損益計算書（12グループ）
• 📊 国際収支 — 経常収支、IIP、国際投資ポジション
• 🔍 汎用キューブアクセス — ID を指定して任意の SNB データキューブまたはウェアハウスキューブを照会
• 🔓 認証不要 — 完全公開の SNB データポータル

---

前提条件

• Python 3.11+
• uv または pip
• MCP 対応クライアント（Claude Desktop、Claude Code、または任意の MCP ホスト）

---

インストール

uvx 経由（推奨 — 永続的なインストールは不要です）：

uvx swiss-snb-mcp

pip 経由：

pip install swiss-snb-mcp

ソースから：

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

---

使い方／クイックスタート

Claude Desktop — claude_desktop_config.json に追加します：

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

設定ファイルの場所：

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

Claude Desktop ですぐに試してみましょう：

「SNB によると、現在の EUR/CHF 為替レートはいくらですか？」 「過去 12 か月の SNB バランスシートを表示してください。金と外貨準備高をお願いします。」

---

設定

API キーや認証は不要です。SNB データポータルは完全に公開されています。

任意の環境変数：

変数	デフォルト	説明
SNB_TIMEOUT	15	HTTP リクエストのタイムアウト（秒）

---

利用可能なツール

フェーズ 1 — 専用ツール

ツール	説明
snb_get_exchange_rates	EUR、USD、JPY、GBP、CNY、およびその他 22 通貨の月次 CHF 為替レート
snb_get_annual_exchange_rates	年平均為替レート（1980 年以降のデータ）
snb_get_balance_sheet	SNB のバランスシート項目（百万 CHF 単位、月次）
snb_convert_currency	SNB の公式レートを使用して任意の金額を CHF に換算

フェーズ 2 — 汎用キューブツール

ツール	説明
snb_get_cube_data	ID を指定して任意の SNB キューブにアクセス
snb_get_cube_metadata	任意のキューブのディメンションとフィルター値を確認

フェーズ 3 — ウェアハウス API（銀行統計）と国際収支

ツール	説明
snb_get_banking_balance_sheet	銀行グループ別の銀行バランスシート（月次／年次、資産／負債）
snb_get_banking_income	銀行グループ別の銀行損益計算書（年次）
snb_get_balance_of_payments	国際収支と国際投資ポジション（四半期）
snb_get_warehouse_data	ID を指定して任意の SNB ウェアハウスキューブにアクセス
snb_get_warehouse_metadata	ウェアハウスキューブのディメンションと最終更新日時を確認

リソース（静的カタログ）

ツール一覧が膨らまないよう、検出に役立つ情報はツールではなく MCP リソースとして提供されます：

URI	説明
data://snb/currencies	ラベルと単位を含む全 28 通貨の ID
data://snb/balance-sheet-positions	資産と負債の項目 ID
data://snb/cubes	検証済みの全 Cube-API ID（フェーズ 1～2）と検出ガイド
data://snb/warehouse-cubes	利用可能なウェアハウスキューブ ID（BSTA）
data://snb/bank-groups	ラベルを含む全 12 銀行グループの ID

使用例

クエリ	ツール
「現在の EUR/CHF レートはいくらですか？」	snb_get_exchange_rates
「CHF 10,000 を USD に換算してください」	snb_convert_currency
「過去 1 年間の SNB の金準備高を表示してください」	snb_get_balance_sheet
「現在の SNB 政策金利はいくらですか？」	snb_get_cube_data（キューブ：snbgwdzid）
「SNB、Fed、ECB の金利を比較してください」	snb_get_cube_data（キューブ：snboffzisa）
「SARON 3M 複利金利はいくらですか？」	snb_get_cube_data（キューブ：zirepo）
「M3 マネーサプライはどれくらいの速さで増加していますか？」	snb_get_cube_data（キューブ：snbmonagg）
「スイスの全銀行の総資産はいくらですか？」	snb_get_banking_balance_sheet
「州立銀行の損益計算書を表示してください」	snb_get_banking_income（bank_group：G10）
「スイスの国際収支を教えてください」	snb_get_balance_of_payments
「利用可能なキューブを教えてください」	リソース data://snb/cubes

→ 対象者別の使用例 →

---

安全性と制限

項目	詳細
アクセス	読み取り専用（readOnlyHint: true）— サーバーはデータを変更または削除できません
個人データ	個人データはありません — すべてのデータソースは、集計済みの公開マクロ経済統計です
レート制限	SNB Warehouse API には WAF による保護があります（約100件の連続リクエスト後に HTTP 503 が返されます）。サーバーは指数バックオフで自動的に再試行します（最大3回、待機時間は2／4／8秒）
タイムアウト	API 呼び出しごとに15秒
認証	API キーは不要です — 両 API（/api/cube/ と /api/warehouse/cube/）は一般公開されています
データソース	スイス国立銀行 — data.snb.ch
利用規約	SNB の利用規約および著作権が適用されます。データは出典を明記すれば非商用目的で無料で利用できます

---

アーキテクチャ

┌─────────────────┐     ┌───────────────────────────┐     ┌──────────────────────┐
│   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 │
                                                          └──────────────────────┘

キューブ探索パターン

SNB API は一貫したキューブベースの構造に従っています。data://snb/cubes リソースを読み込んで検証済みのキューブ ID を確認し、次に snb_get_cube_metadata でディメンションを調べてから、snb_get_cube_data でクエリを実行してください。フェーズ3では、詳細な銀行統計を取得するために Warehouse API（/api/warehouse/cube/）が追加されます。data://snb/warehouse-cubes および data://snb/bank-groups リソースから始めてください。

---

プロジェクト構成

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

---

既知の制限事項

• 為替レート： 月次平均のみです — この API では日中レートや日次レートを取得できません
• 貸借対照表： データは月次です。一部の項目では公開までに1～2か月の遅れが生じる場合があります
• キューブへのアクセス： キューブ ID は SNB によって公式に文書化されていません — 検証済みの ID は data://snb/cubes リソースを読んで確認してください
• 過去データの範囲： 収録期間は系列によって異なります。為替レートは1980年まで遡りますが、一部の金利系列はそれより後に始まります
• 予測なし： すべてのデータは過去の実績値です — SNB はこの API を通じて予測を公開していません

---

MCP プロトコルのバージョン

このサーバーは、同じエンドポイントで2つのプロトコル時代に対応しています。接続時のクライアントの最初のリクエストによって、どちらが適用されるかが決まります。もう一方の時代に属する要求が後から送られても拒否されます。

時代	リビジョン	どのクライアントが利用するか
initialize ハンドシェイク	2024-11-05 … 2025-11-25	現在のクライアントが使用するリビジョンです。サーバーは要求されたリビジョンで応答するか、より新しいリビジョンが要求された場合は上限の 2025-11-25 で応答します。
リクエストごとのエンベロープ	2026-07-28	2026-07-28 の _meta エンベロープを含むリクエストによって、最新の接続が開始されます。

どちらのリビジョンも tests/test_protocol_version.py で固定され、 インストール済みの SDK に対して検証されます。そのため、Dependabot が mcp を更新しても、どちらかのリビジョンが気付かないうちに変わることはありません。

上の表は推測ではなく、実測に基づいています。同じゲートが、インメモリのストリームペア上でサーバーの実際の処理ループ（本番環境では stdio で実行されるループ）を動かし、実際の JSON-RPC フレームを送信します。エンベロープ付きのリクエストは 2026-07-28 で処理され、2026-07-28 を要求する initialize には 2025-11-25 で応答し、すでに決定済みの接続で別の時代のリビジョンが要求された場合は拒否されます（一方は -32022、もう一方は -32600）。このセクションの以前の版では、実測には ASGI アプリが必要だと記載していましたが、実際には不要です。最新の時代には initialize がなく、そもそもハンドシェイクが HTTP 上で行われたことはありません。

サーバーが自身について報告する内容も、同じ方法で tests/test_server_identity.py にて実測されています。パッケージのバージョンとプロジェクトの URL は、コンストラクターではなく、通信上の応答から取得されます。

SDK の LATEST_PROTOCOL_VERSION はハンドシェイク時代ではなく、最新の時代を示すエイリアスである点に注意してください。これだけを基準に固定すると、現在のクライアントが実際にネゴシエートする時代の変更が見逃される可能性があります。

更新ポリシー。 ゲートで失敗した場合、定数をむやみに編集しないでください。2つのリビジョン間の仕様変更履歴を読み、サーバーが引き続き正しく動作することを確認してから、定数、このセクション、README.de.md、および CHANGELOG.md をまとめて更新してください。

---

テスト

# 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

ユニットテストのペイロードは捏造したものではなく、記録されたものです。各ファイルの出典、取得日、選定ルール、SHA-256 は tests/fixtures/PROVENANCE.md に記載されています。手書きのモックには作者の想定が反映されるため、それを否定することは決してできません。実稼働コードとフィクスチャは同じコミットから取得されるため、両方に誤りがあれば、どちらにも同じ誤りが含まれ、テストスイートは成功したままになります。各ファイルにはすべての系列が含まれ、短縮されるのは値のリストだけです。コードは次元を基に処理し、値は表示するだけなので、「最初の N 個の系列」を削除していたら、3つの調査結果の根拠そのものが隠れてしまっていたでしょう。

---

変更履歴

CHANGELOG.md を参照してください。

---

貢献

問題の報告、新しい SNB キューブ ID の提案、コードの貢献に関するガイドラインは、CONTRIBUTING.md を参照してください。

---

セキュリティ

このサーバーは読み取り専用で、個人データを処理せず、data.snb.ch とのみ通信します。セキュリティ対策の全容、監査結果、脆弱性の報告方法については、SECURITY.md を参照してください。

---

ライセンス

MIT License — LICENSE を参照してください。

---

作者

Hayal Oezkan · github.com/malkreide

---

クレジットと関連プロジェクト

• データ： Swiss National Bank — SNB データポータル（公開 REST API）
• プロトコル： Model Context Protocol — Anthropic / Linux Foundation
• 関連： zurich-opendata-mcp — チューリッヒ市のオープンデータ向け MCP サーバー
• 関連： swiss-transport-mcp — スイスの公共交通機関向け MCP サーバー
• ポートフォリオ： Swiss Public Data MCP Portfolio

インストール

uv の uvx で実行します。クローンや手動でのインストールは不要です。MCP クライアントの設定に追加してください（Claude Desktop、Cursor、Windsurf では mcpServers を使用し、.vscode/mcp.json の VS Code ではトップレベルの servers キーを使用します）。

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