🇨🇭 Part of the Swiss Public Data MCP Portfolio — open-source MCP servers connecting AI agents to Swiss public and open data. This is a private project. It is independent of any employer or institutional affiliation.

🏛️ swiss-efv-mcp

MCP server for Swiss federal finances (EFV): budget, debt, forecasts and spending by task and institution.

🇩🇪 Deutsche Version

Overview

This server closes the fiscal gap in the portfolio's Economics & Finance cluster. swiss-snb-mcp already covers monetary policy; swiss-efv-mcp adds the state budget — federal revenue, expenditure, balance, debt ratios (with forecasts to 2029), a hierarchical budget drill-down, and spending by department. Data comes from the Eidgenössische Finanzverwaltung (EFV) via opendata.swiss (OGD Schweiz).

Features

• Five read-only tools over the curated EFV FS/GFS dump files.
• Headline series 1990–2029 per household (bund, ktn, gdn, staat, sv) and model (FS / GFS); every point carries is_projection so actuals and plan/forecast years are unambiguous.
• Hierarchical federal-budget drill-down and spending by department / unit.
• 24 h TTL in-memory cache with stale-serve fallback; retry with exponential backoff (2/4/8 s); dump_status never returns empty silently.
• Dual transport: stdio (local) and SSE (cloud).
• No authentication required — public open-government data (No-Auth-First).

🎯 Anchor Demo Query

"How has the federal balance developed since the SNB rate turnaround in 2022 — and which task areas absorbed the growth in spending?"

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

Cross-read with swiss-snb-mcp, this connects the interest-rate cycle to the federal deficit — something neither server can answer alone.

Demo

Prerequisites

• Python 3.11+
• uv / uvx (recommended) or pip
• Network access to data.finance.admin.ch and efv.admin.ch — no API key needed

Installation

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

Quickstart

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

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

Configuration

All configuration is loaded once into a typed Settings object (pydantic-settings). The legacy unprefixed names below keep working; the canonical names use the EFV_MCP_ prefix. Defaults are safe for local use.

Cloud (Render / Railway):

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

Available Tools

All tools are read-only: each is annotated readOnlyHint: true, destructiveHint: false, only issues HTTP GETs against the EFV dump files, and has no write, send, or filesystem capability.

MCP primitives. This server uses only the Tools primitive. The EFV data are sliced live from cached dumps with no stable resource hierarchy to expose as Resources, and there are no server-authored Prompts. The five tools are small and closely related, so they live in a single server.py rather than a tools/ package.

Architecture

                      ┌──────────────────────────────┐
   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

Architecture decision

This server uses Architecture C (Dump-first).

Rationale (verified live on 2026-07-24):

• The EFV FS/GFS dashboard has no filtered query API; it serves static CSV dumps that its front-end filters in the browser.
• Three curated files are small enough to fetch-and-cache whole (516 KB / 5 MB / 1 MB). They cover the headline aggregates, the hierarchical budget and the by-institution view — i.e. the answerable questions.
• The full detail cubes (standardauswertung.csv 157 MB, fir_art_funk.csv 1.23 GB) are out of scope for v0.1.0; loading them per request is not viable. A future Phase 2 would pre-process them into SQLite/Parquet.

Consequences:

• Files are cached in memory with a 24 h TTL; stale cache is preferred over an empty response when upstream is down.
• Retry with exponential backoff on all HTTP; dump_status always returns a readable state.

Project Structure

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

Safety & Limits