Part of the Swiss Public Data MCP Portfolio

🏛️ swiss-courts-mcp

MCP Server for Swiss court decisions — Federal Supreme Court (BGer), Federal Administrative Court (BVGer), Federal Criminal Court (BStGer), and all 26 cantonal courts via entscheidsuche.ch

Deutsche Version

Overview

Access Swiss court decisions from all judicial levels through a single MCP interface. Combines full-text search with structured filters for canton, court level, date range, and law references.

🎯 Anchor demo query: "Find Federal Supreme Court case law on data protection (Art. 25 DSG) since 2020 — and if entscheidsuche.ch is down, still answer from the offline dump, clearly flagged."

Synergy with fedlex-mcp: Legislation (SR) + case law = complete legal research.

Availability: entscheidsuche.ch is non-profit infrastructure without an SLA. When it is unreachable, the server transparently falls back to a cached public dump (see Offline fallback). Every response declares its origin (source: "live" | "dump"), and dump answers carry a coverage_note — the fallback is partial, not equivalent.

Features

• Full-text search across all Swiss court decisions
• Multi-stage law reference search with regex parser and Elasticsearch boost scoring
• Dedicated Federal Supreme Court search with chamber filter
• Canton and court level filtering
• Recent decisions feed
• Court taxonomy listing
• Decision statistics with aggregations
• Trilingual support (German, French, Italian)
• Offline fallback to a cached public dump when entscheidsuche.ch is unreachable — with explicit provenance on every response
• No API key required

Prerequisites

• Python 3.11 or higher
• An MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.)

Installation

pip install swiss-courts-mcp

Or install from source:

git clone https://github.com/malkreide/swiss-courts-mcp.git
cd swiss-courts-mcp
pip install -e ".[dev]"

Quickstart

# Run directly
swiss-courts-mcp

# Or via Python module
python -m swiss_courts_mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "swiss-courts": {
      "command": "python",
      "args": ["-m", "swiss_courts_mcp"]
    }
  }
}

Cloud Deployment (HTTP transport)

The HTTP transport is off by default. The default bind host is 127.0.0.1 (loopback only) — 0.0.0.0 must be opted into explicitly (the Dockerfile does this). Running HTTP without authentication logs a warning; only do so behind an authenticating reverse proxy.

# Local HTTP (loopback), no auth — development only
swiss-courts-mcp --http --port 8000

# Container (binds 0.0.0.0, auth enabled) — see Dockerfile
docker build -t swiss-courts-mcp .
docker run -p 8000:8000 -e MCP_AUTH_SECRET="$(openssl rand -hex 32)" swiss-courts-mcp

Relevant environment variables (see .env.example):

Authentication validates the user identity from the JWT sub claim only; see ADR 0001.

Offline fallback (env)

Pre-warm the cache (downloads the ~120 MB SCD CSV once, so the first real outage does not pay the download cost):

SWISS_COURTS_FORCE_DUMP=1 python -m swiss_courts_mcp  # then issue one search

MCP Protocol Version

This server pins MCP protocol version 2025-11-25 (constant PROTOCOL_VERSION in server.py). A regression test detects drift against the installed SDK so a protocol bump is a conscious change (version + CHANGELOG + this section). SDK updates land monthly via Dependabot.

Project Phase

Phase 1 — read-only (see ROADMAP.md). All tools are readOnlyHint: true; there are no writing or destructive operations. A move to Phase 2 (write) requires a clean re-audit and the gates listed in the roadmap.

Available Tools

Court Decision Search

Court Information

Tool Annotations

All eight tools share the same hints — they are read-only, idempotent, non-destructive, and reach an external system:

A rechtsrecherche prompt is also provided (a second MCP primitive alongside tools).

Example Use Cases

→ More use cases by audience →

Architecture

┌─────────────────────────────────────┐
│         MCP Client (LLM)            │
│   Claude / Cursor / Windsurf        │
└──────────────┬──────────────────────┘
               │ MCP Protocol
┌──────────────▼──────────────────────────────┐
│              swiss-courts-mcp               │
│  8 tools · Pydantic validation              │
│  Elasticsearch query builder                │
│  Provenance envelope: source = live | dump  │
└───────┬──────────────────────────────┬──────┘
        │ ① live (default)             │ ② fallback
        │ HTTPS POST/GET               │ on bot-block / 5xx / 429 /
        │                              │ timeout, or SWISS_COURTS_FORCE_DUMP=1
┌───────▼──────────────────┐   ┌───────▼───────────────────────────────┐
│     entscheidsuche.ch    │   │   SCD dump — Zenodo 14867950 (CC BY)  │
│  Elasticsearch backend   │   │   lazy download → platformdirs cache  │
│  Federal + 26 cantons    │   │   → local SQLite search               │
│  no auth · no SLA        │   │   BGer only · 2007–2024 · no full text │
└──────────────────────────┘   └───────────────────────────────────────┘

Architecture decision

This server uses Architecture C (metadata-only offline fallback), delivered via lazy download (Option A mechanics) — decided after a live probe on 2026-07-19:

• Live-first, always. entscheidsuche.ch remains the sole source on success; its behaviour is unchanged. The fallback only engages on an availability failure (bot-block, HTTP 5xx/429, timeout, connect error) or when forced.
• Source: the SCD dump (Zenodo 10.5281/zenodo.14867950, Version 2024-3, CC BY 4.0), the ~120 MB CSV — metadata/regesten only, no full text. The 375 MB full-text Parquet and its heavy pyarrow dependency were rejected: a partial fallback does not justify the footprint, and full text would fake an equivalence that does not exist (BGer only).
• A second candidate was rejected: Zenodo 5529712 ("SwissJudgmentPrediction") is CC BY-NC-SA 4.0 — incompatible with this MIT project.
• Consequences: the CSV is cached on disk (platformdirs) and searched via SQLite; update detection uses the Zenodo versions API (conceptrecid 7793043). Every response declares source (live/dump) and dump responses add a coverage_note. CC-BY attribution ships in the tool output, not only here.

Offline fallback

The fallback is a behaviour of the existing tools, not a separate search tool (only get_fallback_status was added, for transparency). It is partial, not equivalent to the live source:

• Only the Federal Supreme Court (BGer/BGE), 2007–2024, no full text.
• Bundesverwaltungsgericht, Bundesstrafgericht and all 26 cantons are NOT covered. A cantonal or non-BGer query in dump mode returns an explicit "not covered" answer — never a silent empty result.
• get_court_decision is best-effort in dump mode: SCD case ids (docref, e.g. 1C_517/2016) differ from entscheidsuche signatures, so some lookups are honestly reported as non-resolvable.
• If neither live nor dump is available, tools return a clear, actionable error (no crash, no stack trace).

Inspect the cache and coverage at any time with get_fallback_status.

Safety & Limits

Project Structure

swiss-courts-mcp/
├── src/
│   └── swiss_courts_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py            # MCP server, 8 tools + 1 prompt, lifespan, auth wiring
│       ├── api_client.py        # HTTP client, ES query builder, egress allow-list
│       ├── fallback.py          # offline dump layer (Zenodo → cache → SQLite)
│       ├── auth.py              # JWT bearer-token verifier (HTTP transport)
│       ├── config.py            # Settings object (env-driven)
│       ├── logging_config.py    # structured logging on stderr
│       └── models.py            # structured response envelope (provenance: live|dump)
├── tests/                       # unit (respx-mocked) + live + security tests
├── docs/                        # egress, secret-management, ADRs
├── .github/workflows/           # ci · security (gitleaks) · live · publish
├── Dockerfile                   # hardened container (non-root, 0.0.0.0 only here)
├── ROADMAP.md
├── pyproject.toml · CHANGELOG.md · LICENSE
├── CONTRIBUTING.md · CONTRIBUTING.de.md
├── SECURITY.md · SECURITY.de.md
└── README.md · README.de.md

Note (single-file tools): the 8 tools live in server.py rather than a tools/ package. At this count a single module stays readable; the registry (register_tools) keeps registration declarative. This is a deliberate deviation from the "split when > 5 tools" convention and will be revisited if the tool count grows. The offline-fallback logic is isolated in fallback.py, cleanly separated from the live client.

Known Limitations

• Search is limited to decisions indexed by entscheidsuche.ch (not all decisions are publicly available)
• Full-text document content is not returned — only metadata, title, and abstract
• Statistics depend on Elasticsearch aggregation support of the backend
• The court taxonomy structure from Facetten_alle.json may vary

Offline fallback (partial coverage — read this): the fallback is a safety net for availability, not an equivalent mirror of the live source:

• Court scope: Federal Supreme Court only (BGer/BGE). Bundesverwaltungsgericht, Bundesstrafgericht and all 26 cantonal courts are not covered.
• Time span: 2007 – December 2024 (the SCD dump's range). Decisions outside this window are not in the dump.
• Content: metadata/regesten only — no full text offline.
• Update latency: the SCD dump is refreshed roughly quarterly on Zenodo, so the offline data lags the live index. get_fallback_status reports the cached version and can check Zenodo for a newer one.
• Law-reference search offline only matches references named in the decision's subject/regest (topic/issue) — there is no offline cited-law index.
• Responses always disclose their origin via source (live/dump) and a coverage_note; the server never silently narrows coverage.

Testing

Unit tests mock all HTTP with respx; live tests hit the real API and run in a separate nightly workflow (live.yml), never blocking PRs.

Run from the project root with PYTHONPATH=src:

# Unit tests (HTTP mocked) — what CI runs
PYTHONPATH=src pytest tests/ -v -m "not live"

# Live API tests (real entscheidsuche.ch + Zenodo)
PYTHONPATH=src pytest tests/ -v -m live

# Linting
ruff check src/ tests/
ruff format src/ tests/

The offline-fallback tests use a small committed schema fixture (tests/fixtures/scd_sample.csv) and mock the Zenodo download with respx — the full ~120 MB dump is never committed or downloaded in CI.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the security posture and how to report a vulnerability.

License

MIT

Author

Hayal Oezkan · malkreide

Credits & Related Projects

• entscheidsuche.ch — Swiss court decision search engine (live source)
• Swiss Federal Supreme Court Dataset (SCD) — offline fallback source, CC BY 4.0: Geering, F. & Merane, J. (2025). Swiss Federal Supreme Court Dataset (SCD), Version 2024-3. Zenodo. https://doi.org/10.5281/zenodo.14867950
• fedlex-mcp — MCP Server for Swiss federal law (legislation synergy)
• zurich-opendata-mcp — MCP Server for Zurich open data
• Model Context Protocol — Open protocol for AI tool integration

Installation

Run via 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):

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