swiss-efv-mcp

🇨🇭 スイス公共データ MCP ポートフォリオ の一部 — AI エージェントをスイスの公共データおよびオープンデータに接続する、オープンソースの MCP サーバーです。 これは個人プロジェクトです。雇用先や所属機関とは関係ありません。

🏛️ swiss-efv-mcp

スイス連邦財務局（EFV）の財政を扱う MCP サーバーです。予算、債務、予測、目的別・機関別支出を確認できます。

🇩🇪 ドイツ語版

概要

このサーバーは、ポートフォリオの経済・金融クラスターにおける財政データの不足を補います。 swiss-snb-mcp はすでに金融政策を扱っており、swiss-efv-mcp は国家予算、すなわち連邦歳入、歳出、収支、債務比率（2029年までの予測を含む）、階層的な予算の詳細分析、部門別支出を追加します。データは opendata.swiss（OGD Schweiz）経由で、スイス連邦財務局（EFV）から取得します。

特徴

• EFV の FS/GFS キュレーション済みダンプファイルを使う、読み取り専用ツールを5つ提供します。
• 世帯区分（bund、ktn、gdn、staat、sv）およびモデル（FS / GFS）ごとに、1990～2029年の主要系列を収録します。すべてのデータポイントに is_projection が付いているため、実績値と計画・予測期間を明確に区別できます。
• 連邦予算の階層的な詳細分析と、部門・単位別の支出を確認できます。
• 24時間の TTL を設定したインメモリーキャッシュと、期限切れデータを提供するフォールバックを備えています。指数バックオフ（2/4/8秒）で再試行し、dump_status が何も返さずに終了することはありません。
• トランスポートは stdio（ローカル）と SSE（クラウド）の2種類に対応しています。
• 認証は不要です — 公開されたオープンガバメントデータを使用します（No-Auth-First）。

🎯 デモ用の代表的なクエリ

「2022年の SNB 利上げ転換以降、連邦収支はどのように推移しましたか？ また、支出の増加を吸収したのはどの目的分野ですか？」

fiscal_headline(variable="saldo", household="bund", year_from=2021)
fiscal_budget_breakdown(topic="Ausgaben nach Aufgabengebiet", level=2)

swiss-snb-mcp と相互にデータを読み解くことで、金利サイクルと連邦財政赤字を結び付けられます。これはどちらか一方のサーバーだけでは答えられない問いです。

デモ

前提条件

• Python 3.11+
• uv / uvx（推奨）または pip
• data.finance.admin.ch と efv.admin.ch へのネットワークアクセス — API キーは不要です

インストール

uvx swiss-efv-mcp            # zero-install run (once published to PyPI)
# or
pip install swiss-efv-mcp

Claude Desktop（claude_desktop_config.json）：

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

クイックスタート

# Run locally over stdio (default transport)
uvx swiss-efv-mcp

# From a checkout, without installing
PYTHONPATH=src python -m swiss_efv_mcp

設定

すべての設定は、一度だけ型付きの Settings オブジェクト （pydantic-settings）に読み込まれます。以下の接頭辞なしの従来の名前も引き続き使用できます。標準の名前には EFV_MCP_ 接頭辞が付きます。デフォルト値はローカルでの使用に適しています。

変数	デフォルト値	用途
TRANSPORT	stdio	トランスポート：stdio（Claude Desktop）または sse / streamable-http（クラウド）
HOST	127.0.0.1	バインドするホスト（SSE のみ）。デフォルトではループバックです。コンテナー内でのみ 0.0.0.0 に設定してください
PORT	8000	バインドするポート（SSE のみ）
EFV_MCP_LOG_LEVEL	INFO	structlog のレベル（stderr に JSON を出力）
EFV_MCP_CORS_ORIGINS	[]	SSE のみ：許可するブラウザーオリジンを明示的に指定（デフォルトではすべて拒否。カンマ区切りまたは JSON）
EFV_MCP_OTEL_ENABLED	false	OpenTelemetry トレースを有効化（otel エクストラが必要）。標準の OTEL_* 環境変数でエクスポートを設定

クラウド（Render / Railway）：

TRANSPORT=sse PORT=8000 swiss-efv-mcp   # exposes /sse

利用可能なツール

ツール	用途
fiscal_headline	1990～2029 年の歳入／歳出／収支／債務比率。世帯単位およびモデル別。各データポイントに is_projection フラグが付きます
fiscal_budget_breakdown	トピック別の連邦予算の階層データ（Ausgaben nach Art / nach Aufgabengebiet, Einnahmen, Bilanz, …）
fiscal_by_institution	2007 年以降の部局／行政単位別の支出（Personalausgaben, Informatik, 外部サービス、FTE）
fiscal_list_dimensions	有効なパラメーター値を確認します。正しい引数を組み立てるため、最初に呼び出してください
fiscal_status	データセットごとのキャッシュの鮮度と上流の状態。何も返さずに終了することはありません
dump_status	fiscal_status の非推奨エイリアス（後方互換性のために保持。将来のマイナーバージョンで削除予定）

すべてのツールは読み取り専用です。それぞれに readOnlyHint: true、 destructiveHint: false の注釈が付いており、EFV ダンプファイルに対して HTTP GET のみを実行します。 書き込み、送信、ファイルシステムの機能はありません。

MCP のプリミティブ。 このサーバーでは Tools プリミティブのみを使用します。EFV データはキャッシュされたダンプからリアルタイムに切り出されますが、Resources として公開できる安定したリソース階層はなく、サーバーが作成した Prompts もありません。5 つのツールは小規模で互いに密接に関連しているため、tools/ パッケージではなく、単一の server.py にまとめられています。

アーキテクチャ

                      ┌──────────────────────────────┐
   Claude / Agent ──▶ │  swiss-efv-mcp (FastMCP)      │
                      │  5 tools · Pydantic v2 env.   │
                      └───────────────┬──────────────┘
                                      │ fetch + retry + TTL cache
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
   data.finance.admin.ch                          efv.admin.ch/dam
   fs_dashboard/main_extern.csv                   bundeshaushalt_de.csv
   (headline, 1990–2029)                          institutionen_de.csv

アーキテクチャの決定

このサーバーでは アーキテクチャ C（ダンプ優先） を採用しています。

根拠（2026-07-24 に実環境で確認）：

• EFV FS/GFS ダッシュボードにはフィルター付きのクエリ API がありません。フロントエンドがブラウザー内でフィルタリングする静的 CSV ダンプを提供しています。
• 厳選された 3 つのファイルは、全体を取得してキャッシュするのに十分小規模です（516 KB / 5 MB / 1 MB）。これらは主要な集計データ、階層化された予算、機関別のビュー、つまり回答可能な質問を網羅しています。
• 詳細キューブ全体（standardauswertung.csv 157 MB、fir_art_funk.csv 1.23 GB）は v0.1.0 の対象外です。リクエストごとに読み込むのは現実的ではありません。将来のフェーズ 2 では、SQLite/Parquet に前処理する予定です。

結果：

• ファイルはメモリーに 24 時間の TTL でキャッシュされます。上流が停止している場合は、空のレスポンスよりも古いキャッシュを優先します。
• すべての HTTP リクエストで指数バックオフによる再試行を行います。dump_status は常に読み取り可能な状態を返します。

プロジェクト構成

swiss-efv-mcp/
├── src/swiss_efv_mcp/
│   ├── __init__.py
│   ├── __main__.py        # entry point; dual transport (stdio / SSE+CORS)
│   ├── client.py          # dump-first data layer: egress allow-list, retry, UA, TTL cache
│   ├── logging_config.py  # structlog JSON to stderr
│   ├── models.py          # Pydantic v2 envelopes (source + provenance)
│   ├── server.py          # 5 FastMCP tools (annotated) + testable *_impl functions
│   └── settings.py        # typed pydantic-settings config
├── tests/                 # respx mock tests + hardening tests + @pytest.mark.live
├── docs/                  # network-egress.md + accepted-risk ADRs
├── audits/                # MCP best-practice audit runs (findings, report, summary)
├── README.md · README.de.md · CHANGELOG.md · SECURITY.md · CONTRIBUTING.md
├── Dockerfile · server.json · LICENSE
└── pyproject.toml

安全性と制限事項

• 読み取り専用です。 すべてのツールに readOnlyHint: true が注釈されており、EFV のダンプファイルに対して HTTP GET のみを実行します。書き込み、送信、ファイルシステムの機能はありません。
• 送信先の許可リスト。 不変の ALLOWED_HOSTS frozenset と assert_host_allowed() により、すべてのリクエストの前に許可されていることを確認します（HTTPS のみ、固定された EFV ホスト 2 件）。URL は ハードコードされた定数であり、ユーザー入力から URL が組み立てられることはありません。docs/network-egress.md を参照してください。
• TLS が有効です。 httpx の証明書検証はデフォルトで有効で、無効化されることはありません。
• 認証情報はありません。 エンドポイントは公開 OGD であり、API キーやシークレットを保存したり転送したりしません。 エンドポイントがデフォルトの httpx/curl UA に対して 403 を返すため、ブラウザーの User-Agent を注入しています（「既知の制限事項」を参照）。これは削除しないでください。
• エラー情報のマスキング。 mask_error_details=True とクライアント側のマスキングにより、未加工の上流／内部情報がツールの結果に含まれないようにしています。詳細情報は structlog の stderr ログにのみ出力されます。
• 入力の制限。 ツールの引数には、明示的な Pydantic 制約（年 1900–2100、level 1–8、文字列の max_length）が設定されています。
• 適切な縮退動作。 指数バックオフ（2/4/8 秒）で再試行します。空の応答ではなく、古いキャッシュを返します。dump_status は常に読み取り可能な状態を返し、理由を示さずに空の結果を返すことはありません。
• ループバックとデフォルト拒否の CORS。 SSE は HOST にバインドされ、デフォルトは 127.0.0.1 です。HOST=0.0.0.0 を設定するのは、コンテナ内に限ってください（提供されている Dockerfile では設定済みです）。 ブラウザーのオリジンは EFV_MCP_CORS_ORIGINS で明示的に指定する必要があります。
• 監査済みです。 MCP のベストプラクティス集（該当する 44 項目）に照らしてレビュー済みです。詳細は audits/ と SECURITY.md を参照してください。 受容済みのリスクは、docs/adr/ 配下の ADR に記録されています。
• 正式な情報ではありません。 数値は公式なものではありません。公式な用途には EFV の原資料を参照してください。

既知の制限事項

ライブプローブの調査結果（2026-07-24）。CHANGELOG.md → Known findings にも記載されています。

調査結果	影響
ブラウザーの User-Agent がない場合、エンドポイントは HTTP 403 を返す	UA はクライアントが注入します。削除しないでください
opendata.swiss の 2 つのデータセットの「CSV」リンクが HTML のランディングページを指している	実ファイルは DAM パス（/dam/de/sd-web/{id}/…）に解決されます。再アップロード時に不透明な ID が変わる可能性があります
hh／model／source に NA が文字列として含まれる	一元的に None に変換されます
「将来予測」は 単一のラベルではありません。Bund では「Budget/financial plans」、staat では「Forecasts」が使用されています	is_projection により抽象化されています
2022/2023 年に会計モデルが切り替わっています（トピックが「bis 2022」から「ab 2023」へ変更）	系列に継ぎ目があり、影響を受けるトピックには note が付されています
詳細キューブ（157 MB／1.23 GB）は提供されていません	フェーズ 2 で対応予定です。それまでは精選されたファイルを使用してください

プロジェクトのフェーズ

このサーバーは フェーズ 1（読み取り専用） です。すべてのツールは公開されている EFV のダンプファイルを取得するだけで、書き込み、送信、ファイルシステムの機能はありません。

フェーズ	対象範囲	状態
1 — 読み取り専用	主要系列、予算の内訳、機関別の支出	✅ 現行
2 — 詳細キューブ	157 MB／1.23 GB のキューブを SQLite/Parquet に前処理	予定
3 — マルチエージェント	（予定なし）	—

後続フェーズへ移行する際は、書き込み機能を持つツールを追加する前に再監査が必要です。

MCP プロトコルバージョン

このサーバーは MCP 仕様の 2026-07-28 にネイティブ対応しており、旧世代のハンドシェイクにも引き続き対応しています。そのため、両方のバージョンを明記しています。単一の番号では、クライアントが実際に利用するものの半分しか表せないためです。

世代	リビジョン	接続時のネゴシエーション方法	定数
モダン（デフォルト）	2026-07-28	server/discover とリクエストごとのエンベロープ。initialize ハンドシェイクはなく、Client.initialize_result は None	MCP_MODERN_PROTOCOL_VERSION
ハンドシェイク（レガシークライアント）	2025-11-25	従来の initialize ハンドシェイク	MCP_HANDSHAKE_PROTOCOL_VERSION

両方の定数は server.py にあり、仕様のテキストをコピーしたものではなく、mcp SDK 自身の LATEST_MODERN_VERSION／LATEST_HANDSHAKE_VERSION に固定されています。また、実際の接続を通じて両世代をテストしているため、プロトコルに影響する SDK の更新があれば、気付かないうちにずれが生じるのではなく、CI で明確に失敗します（ARCH-012）。

2026-07-28 世代には、バージョン番号以外にも影響があります。

• ルーティングヘッダー。 モダンなリクエストにはすべて Mcp-Protocol-Version と Mcp-Method が含まれ、tools/call の場合は Mcp-Name も含まれます。これらは __main__.py の CORS 許可リストに記載されています。これらがないと、ブラウザクライアントはプリフライトで失敗し、サーバーに到達できません。Mcp-Param-* は意図的に含めていません。ここにあるツールスキーマには、クライアントにこのヘッダーを送信させる x-mcp-header アノテーションがなく、将来どれかに追加された場合はテストが失敗します。
• ロギングは非推奨です（SEP-2577）。 ツールハンドラーはクライアント向けのログ通知を送信しなくなりました。呼び出しごとの診断情報は、EFV_MCP_LOG_LEVEL に従って structlog の標準エラー出力ストリームに送られます。進捗報告には影響がなく、引き続き利用できます。
• fastmcp>=4.0 は最低要件であり、見た目だけの指定ではありません。 mcp 2.x が含まれるのは fastmcp 4 のみで、リビジョン 2026-07-28 が存在するのも fastmcp 4 のみです。fastmcp 3.x では、このサーバーが対応できるのは最大でも 2025-11-25 です。

依存関係は、Dependabot による月次 PR（.github/dependabot.yml）で最新の状態に保たれます。プロトコルに関連する更新は CHANGELOG.md に記載しています。

テスト

PYTHONPATH=src pytest tests/ -m "not live"   # offline, respx-mocked
PYTHONPATH=src pytest tests/ -m live         # hits the real EFV endpoints
PYTHONPATH=src ruff check src tests

変更履歴

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

コントリビューション

イシューやプルリクエストを歓迎します。ツールは読み取り専用に保ち、提出前に ruff check とオフラインテストスイートを実行してください。また、ユーザー向けの変更については [Unreleased] の下に CHANGELOG.md の項目を追加してください。CONTRIBUTING.md を参照してください。

メンテナー向け：手順ごとの PyPI リリースプロセス（GitHub Release による Trusted Publishing）については、PUBLISHING.md を参照してください。

セキュリティ

セキュリティ体制、強化対策、脆弱性の報告方法については、SECURITY.md を参照してください。

ライセンス

このサーバーは MIT ライセンスです。LICENSE を参照してください。EFV のデータには OGD Schweiz の利用規約が適用されます（自由に利用できますが、出典の表示が必要です）。

作者

Hayal Oezkan · github.com/malkreide

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

• データ：opendata.swiss 経由の Eidgenössische Finanzverwaltung EFV（OGD Schweiz、自由に利用可能）
• 関連プロジェクト：swiss-snb-mcp（金融政策）— 財政と金融政策の組み合わせ
• ポートフォリオのインデックス：swiss-public-data-mcp

免責事項：個人プロジェクトであり、雇用主や機関とは無関係です。保証はありません。数値は公式なものではありません。公式な用途には EFV の原資料を参照してください。