Swiss Democracy Mcp

🗳️ swiss-democracy-mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio — connecting AI models to Swiss institutional data sources.

🌐 English | 🇩🇪 Deutsche Version

An MCP server providing access to Swiss direct democracy data, covering all federal popular votes since 1848 and elections since 1900.

---

Demo Query

«Wie hat der Kanton Zürich bei der AHV 21 Initiative 2022 abgestimmt,
 und welche Parteien unterstützten die Vorlage?»

→ democracy_search_votes(keyword="AHV 21", year_from=2022)
→ democracy_get_cantonal_results(vote_number="551")
→ democracy_get_party_positions(vote_number="551") → More use cases by audience →

---

Data Sources

Source	Coverage	Auth
Swissvotes (Uni Bern)	All federal votes since 1848 · 874 columns · party positions · cantonal results	None ✓
BFS / opendata.swiss	Real-time & archive (since 1981) · municipality level	None ✓
SRGSSR Polis	Votes & elections since 1900 · municipality detail	OAuth2 key

---

Tools

Phase 1 — Swissvotes (No Auth Required)

Tool	Description
democracy_search_votes	Search all federal popular votes since 1848 by keyword, date range, legal form, outcome, policy domain
democracy_get_vote_detail	Full details for a specific vote: official title, parliamentary positions, national result, signatures
democracy_get_party_positions	Party recommendations (FDP, SP, SVP, Die Mitte, GPS, GLP, …) with campaign finance data
democracy_get_cantonal_results	Results for all 26 cantons: yes%, turnout, accepted flag
democracy_list_vote_dates	List all voting dates with number of proposals per date

Phase 2 — BFS Real-Time (No Auth Required)

Tool	Description
democracy_bfs_list_vote_dates	List all BFS voting dates (archive + current)
democracy_bfs_get_vote_results	Real-time or archived results at national, cantonal, or municipality level

Phase 3 — SRGSSR Polis (API Key Required)

Tool	Description
democracy_polis_list_votations	Historical votations since 1900 with municipality-level data
democracy_polis_get_votation_detail	Full Polis detail, optionally with all municipality results
democracy_polis_list_elections	National Council, Council of States, and cantonal elections since 1900

---

Installation

Claude Desktop (stdio)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "swiss-democracy": {
      "command": "uvx",
      "args": ["swiss-democracy-mcp"],
      "env": {
        "SRGSSR_CONSUMER_KEY": "your_key_here",
        "SRGSSR_CONSUMER_SECRET": "your_secret_here"
      }
    }
  }
}

The SRGSSR_* variables are optional. Without them, all Swissvotes and BFS tools remain fully functional. Only the Polis tools require credentials.

Cloud / Render.com (Streamable HTTP)

pip install swiss-democracy-mcp
# Bind to all interfaces ONLY inside a container/cloud environment:
MCP_TRANSPORT=streamable_http MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m swiss_democracy_mcp.server

MCP_HOST defaults to 127.0.0.1 (loopback). Set MCP_HOST=0.0.0.0 only inside a sandboxed container/cloud deployment — never on a local machine, where it would expose the server to your whole network.

---

Architecture

┌─────────────────────────────────────────────┐
│              Claude / LLM Host              │
└──────────────┬──────────────────────────────┘
               │ MCP (stdio / Streamable HTTP)
┌──────────────▼──────────────────────────────┐
│         swiss-democracy-mcp                 │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │  Swissvotes CSV Cache (24h TTL)     │   │
│  │  All 874 columns, since 1848        │   │
│  └──────────────┬──────────────────────┘   │
│                 │                           │
│  ┌──────────────▼──────────────────────┐   │
│  │  BFS / opendata.swiss (no auth)     │   │
│  │  Real-time & archive since 1981     │   │
│  └──────────────┬──────────────────────┘   │
│                 │                           │
│  ┌──────────────▼──────────────────────┐   │
│  │  SRGSSR Polis (OAuth2, optional)    │   │
│  │  Votes & elections since 1900       │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Transport: stdio for Claude Desktop · Streamable HTTP for cloud/Render.com
Auth pattern: No-Auth-First — Swissvotes & BFS work without any credentials
Cache: Swissvotes CSV is loaded once at startup and cached for 24 hours

---

Configuration

All configuration is via environment variables (see .env.example):

Variable	Default	Purpose
MCP_TRANSPORT	stdio	stdio (local) or streamable_http (cloud)
MCP_HOST	127.0.0.1	HTTP bind address — set 0.0.0.0 only in a container
MCP_PORT	8000	HTTP port
LOG_LEVEL	INFO	structured JSON logs go to stderr
MCP_CORS_ORIGINS	—	comma-separated CORS allow-origins for the HTTP transport. Empty means no browser client is permitted; * allows any origin and is logged as a warning. stdio clients are unaffected
MCP_ALLOWED_HOSTS	—	comma-separated inbound Host allow-list. Only needed for a non-loopback bind
SRGSSR_CONSUMER_KEY / SRGSSR_CONSUMER_SECRET	—	optional, only for democracy_polis_* tools

Secrets are held as SecretStr and never logged. See docs/secret-management.md and docs/security.md.

MCP Primitives

This server intentionally exposes Tools only (no Resources or Prompts). It is a Phase-1 read-only data wrapper (see docs/roadmap.md); the tool surface is small (10 use-case-oriented tools) and every response is self-contained with source provenance. Resources (e.g. vote://{anr}) are a candidate for a later phase once the URI scheme stabilises.

MCP Protocol Version

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Era	Revision	Who reaches it
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.
Per-request envelope	2026-07-28	A request carrying the 2026-07-28 _meta envelope opens a modern connection.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. Next to them, tests/test_server_identity.py sends real requests through the assembled ASGI app: a per-request envelope is answered with the tool list, and an initialize that offers the modern revision still gets the handshake ceiling back. The constants say which revisions the SDK knows; the measurement says which ones this server serves.

Server identity. Under the handshake era serverInfo is named once, in the initialize reply. The modern era has no handshake and stamps the identity onto every response instead, as _meta["io.modelcontextprotocol/serverInfo"]. Implementation.version is a required schema field that the SDK pre-fills with "" when the constructor omits it, so an unset version is not a gap but a value on the wire — and one that a green test suite will not show you. This server passes its distribution version explicitly; test_server_identity.py measures it on both wires, with a bare MCPServer as the negative control.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era — pinning against it alone would leave the era that current clients actually negotiate free to drift.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

---

Portfolio Synergy

Combine with other servers in the Swiss Public Data MCP portfolio:

• zurich-opendata-mcp — add Zurich city-level statistics to vote analysis
• swiss-statistics-mcp — enrich with BFS demographic data by canton
• srgssr-mcp — link SRF news archive content to specific vote dates

Example multi-server query:
«Vergleiche die Abstimmungsresultate zur AHV-Reform mit der Altersstruktur der Kantone»
→ swiss-democracy-mcp + swiss-statistics-mcp

---

Safety & Limits

• Read-only: All tools perform HTTP GET requests only — no data is written, modified, or deleted upstream.
• Egress allow-list (SSRF protection): Outbound requests are restricted to a fixed allow-list of trusted hosts (swissvotes.ch, opendata.swiss, *.bfs.admin.ch, api.srgssr.ch), HTTPS only. Caller-supplied URLs (the BFS result_url) are additionally resolved and rejected if they point at private, loopback or cloud-metadata IP ranges.
• No personal data: Swissvotes, BFS and SRGSSR Polis expose aggregate democratic data (vote results, party positions, cantonal/municipality tallies). No personally identifiable information (PII) is processed or stored by this server.
• Rate limits: Swissvotes is a single CSV downloaded once per 24h and cached in memory. BFS / opendata.swiss and SRGSSR Polis are public APIs without documented rate limits — keep limit and date ranges conservative. The server enforces a 30s timeout per request.
• Data freshness: Real-time BFS results reflect the upstream feed at query time (no local caching). Swissvotes is refreshed every 24h from the Uni Bern mirror.
• Terms of service: Data is subject to the ToS of each source — swissvotes.ch (CC BY 4.0, Uni Bern), opendata.swiss (mostly CC-BY / Open by Default), SRGSSR Polis (free tier, non-commercial use only). Always cite the upstream source in downstream products.
• No guarantees: This server is a community project, not affiliated with the University of Bern, the Federal Statistical Office, or SRG SSR. Availability depends on upstream APIs.

---

Known Limitations

• Swissvotes coverage: Cantonal-level results are available since 1848; municipality-level results only via SRGSSR Polis (since ~1990s depending on the vote).
• BFS archive: Real-time service covers federal votes since 1981 only.
• Polis tools: Require free registration at developer.srgssr.ch. Non-commercial use only.
• CSV cache: The Swissvotes dataset is ~several MB and is cached in memory for 24 hours. Memory footprint is accordingly higher than API-only servers.

---

Testing

# Unit tests (no network required)
PYTHONPATH=src pytest tests/ -m "not live" -v

# Live tests (require network access)
PYTHONPATH=src pytest tests/ -m "live" -v

Where the test data comes from

The fixtures under tests/fixtures/ are recorded from the live sources and dated. Source, retrieval date, selection rule and SHA-256 for every file: tests/fixtures/PROVENANCE.md.

python scripts/record_fixtures.py   # re-record

The selection rule is the point here. The Swissvotes dataset has 714 rows and 874 columns, and the recorded rows are chosen by property, not by position. "The first N rows" would cut away exactly the cells the fixture exists for: the placeholders 9999 ("no information") and . ("not applicable"), which appear in 667 of the 714 votes. A fixture without them would look clean and prove nothing — which is precisely why nobody noticed the tools were passing them through as if they were values.

The byte-order mark stays in the file too, because the source sets one and the server strips it explicitly. Without it the fixture could not show that it has to.

SRGSSR Polis needs OAuth credentials and is listed under NOT RECORDED in PROVENANCE.md rather than given a date it never had.

---

Contributing

See CONTRIBUTING.md (🇩🇪 Deutsch).

---

Security

See SECURITY.md (🇩🇪 Deutsch) for the security posture and vulnerability reporting.

---

License

MIT — see LICENSE.

Data licenses:

• Swissvotes: Creative Commons BY 4.0
• BFS / opendata.swiss: Open use
• SRGSSR Polis: Non-commercial use only — see developer.srgssr.ch

---

Author

Hayal Oezkan · github.com/malkreide

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-democracy-mcp": {
      "command": "uvx",
      "args": [
        "swiss-democracy-mcp"
      ]
    }
  }
}