Srgssr Mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio

📺 srgssr-mcp

[Version] [License: MIT] [Python 3.11+] [MCP] [CI] [Data Source]

MCP server connecting AI models to SRG SSR public APIs – weather, TV/radio metadata, program guide and Swiss votations/elections since 1900 (SRF, RTS, RSI, RTR, SWI).

🇩🇪 Deutsche Version

[Demo: Claude asks a question → srgssr-mcp tool call → grounded answer from SRG SSR Polis API]

Overview

srgssr-mcp gives AI assistants like Claude direct access to the public APIs of SRG SSR – Switzerland's national public broadcaster. Weather forecasts, TV and radio metadata, electronic program guides, and historical democratic data (votations and elections since 1900) are all accessible through a single standardised MCP interface.

The server covers five thematic clusters: SRF Weather, Video, Audio, EPG and Polis (Swiss Democracy). Each cluster maps to a group of purpose-built tools that translate raw SRG SSR API data into clean JSON responses.

Anchor demo query: "What were the cantonal results of the popular vote on initiative X in Zurich?" – answered with historical real-time data from the Polis system, not a hallucination.

Features

• 🌦️ Weather – location search, current conditions, 24h hourly forecast, 7-day forecast (SRF Meteo)
• 📺 Video – TV show listings, latest episodes, live TV channels across all business units
• 🎙️ Audio – radio show listings, audio episodes, live radio stations
• 📅 EPG – daily program schedule for any TV or radio channel
• 🗳️ Polis – popular votes and elections since 1900, national and cantonal results
• 🏢 Multi-unit – SRF (DE), RTS (FR), RSI (IT), RTR (RM), SWI (multilingual)
• 🔐 OAuth2 – automatic token management with Client Credentials flow
• ☁️ Dual transport – stdio for Claude Desktop, Streamable HTTP/SSE for cloud deployment

Prerequisites

• Python 3.11+
• API keys from developer.srgssr.ch (free registration):
  1. Create an account and log in
  2. Under "My Apps", create a new application
  3. Add the product SRG SSR PUBLIC API V2
  4. Note your Consumer Key and Consumer Secret

⚠️ Terms of use: SRG SSR APIs are available for non-commercial use. For commercial use, contact [email protected] directly.

Installation

# Clone the repositorygit clone https://github.com/malkreide/srgssr-mcp.gitcd srgssr-mcp
# Installpip install -e .

Or with uvx (no permanent installation):

uvx srgssr-mcp

Or via pip:

pip install srgssr-mcp

Quickstart

# Set credentialsexport SRGSSR_CONSUMER_KEY="your-consumer-key"export SRGSSR_CONSUMER_SECRET="your-consumer-secret"
# Start the server (stdio mode for Claude Desktop)srgssr-mcp

Try it immediately in Claude Desktop:

"What will the weather be like in Zurich tomorrow?" "What's on SRF 1 tonight?" "Which popular votes took place in the canton of Bern between 2010 and 2020?"

Configuration

Claude Desktop

Minimal (recommended):

{  "mcpServers": {    "srgssr": {      "command": "uvx",      "args": ["srgssr-mcp"],      "env": {        "SRGSSR_CONSUMER_KEY": "your-consumer-key",        "SRGSSR_CONSUMER_SECRET": "your-consumer-secret"      }    }  }}

Config file locations:

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

After saving, restart Claude Desktop completely.

Other MCP Clients

Compatible with Cursor, Windsurf, VS Code + Continue, LibreChat, Cline, and self-hosted models via mcp-proxy. Set the same environment variables.

Cloud Deployment (SSE for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software):

SRGSSR_CONSUMER_KEY=... \SRGSSR_CONSUMER_SECRET=... \SRGSSR_MCP_TRANSPORT=streamable-http \SRGSSR_MCP_HOST=0.0.0.0 \SRGSSR_MCP_PORT=8000 \  python -m srgssr_mcp.server

Transport, host, port and mount path are all driven by environment variables (see srgssr_mcp.server.Settings). Valid values for SRGSSR_MCP_TRANSPORT are stdio (default), sse, and streamable-http.

💡 "stdio for the developer laptop, SSE for the browser."

MCP Primitives

This server exposes all three orthogonal MCP primitives:

Tools cover parametrized searches (year ranges, free-text, paginated listings) where every call may yield different results. Resources expose stable data points that are safe to cache: a published EPG for a given channel/date, or the final result of a closed Swiss votation. Prompts standardise recurring multi-step analyses so users don't have to phrase them from scratch.

Resources

EPG station ids — hyphenated, and not the same as the livestream ids:

Prompts

Available Tools

Tool Naming Convention

This server uses snake_case for tool names, following Python ecosystem idioms. While MCP best practice favors camelCase for optimal LLM tokenization, snake_case remains acceptable and keeps tool names aligned with the underlying Python function identifiers.

All tools follow the pattern srgssr_<domain>_<action> with the namespace prefix srgssr_ and a semantically meaningful <domain>_<action> suffix (e.g. srgssr_weather_current, srgssr_polis_get_votations).

🌦️ SRF Weather (4 tools)

📺 Video (3 tools)

🎙️ Audio (3 tools)

📅 EPG – Electronic Program Guide (1 tool)

🗳️ Polis – Swiss Democracy (3 tools)

Supported Business Units

Example Use Cases

→ More use cases by audience →

Architecture

┌─────────────┐│ Claude / LLM│└──────┬──────┘       │ MCP (stdio)┌──────▼───────────────────┐│ srgssr-mcp Server        ││  ├─ Weather Tools (4)    ││  ├─ EPG Tools (1)        ││  ├─ Polis Tools (3)      ││  ├─ Video Tools (3)      ││  └─ Audio Tools (3)      │└──────┬───────────────────┘       │ HTTPS (OAuth2)┌──────▼──────────────┐│ SRG SSR Public APIs ││  developer.srgssr.ch│└─────────────────────┘

Data Sources

Attribution: SRG SSR APIs are subject to the SRG SSR Terms of Use.

Development Phase

This server is in Phase 1: Read-only Wrapper.

The server exposes only GET-style operations against public SRG SSR APIs. There are no write, mutate or delete capabilities by design — see Safety & Limits for the threat-model implications.

Phase 1 Completion Criteria

• 14 read-only tools across five thematic clusters (Weather, Video, Audio, EPG, Polis)
• OAuth2 Client Credentials authentication with token caching
• Bilingual documentation (EN/DE)
• Test suite (unit + live) — see OPS-001
• Structured logging — see OBS-003 and CHANGELOG
• Production-ready error handling (uniform retry/backoff, typed error envelopes)

Future Phases

• Phase 2 (Write): Not planned. The SRG SSR Public APIs are read-only by contract; there is no upstream surface to write to.
• Phase 3 (Multi-Agent): Evaluation deferred. Will be reconsidered once user feedback indicates concrete multi-agent workflows that this server should orchestrate (e.g. cross-server aggregation with swiss-statistics-mcp or swiss-transport-mcp).

MCP Protocol Version

mcp 2.x serves two protocol eras over the same server, and the client's first request on a connection decides which one applies:

PROTOCOL_VERSION in src/srgssr_mcp/_app.py names the modern era. It is validated at import time against the installed SDK's SUPPORTED_PROTOCOL_VERSIONS — but that list is backwards-compatible and still contains 2024-11-05, so the membership check catches a revision being dropped, never a drift. tests/test_protocol_version.py holds both eras against the SDK and is the check that catches drift. Bumps are tracked in CHANGELOG.md under the matching release.

What the server actually puts on the wire

The table above used to be an assertion held against SDK constants. tests/test_spec_2026_07_28.py now sends real requests through MCPServer.streamable_http_app() over httpx.ASGITransport and asserts the answers, in both eras. What that measurement pins:

The measurement paid for itself on its first run, against 425 green tests and 96% coverage: serverInfo.version was the empty string, every tools/call came back isError (a FastMCP 1.x ctx.info(msg, **kwargs) call shape that mcp 2.x rejects), and eight tools refused the enum string their own published inputSchema advertises (ConfigDict(strict=True) demands an enum instance, which no JSON payload can carry). None of that is visible from inside the process — which is the whole argument for testing the wire.

Update Policy

• SDK dependency updates land via Dependabot (.github/dependabot.yml, monthly cadence, grouped under the mcp-sdk label) and run the full test suite before merge.
• Spec bumps are evaluated on a feature branch against the relevant MCP SDK release; the official MCP changelog is the source of truth for breaking changes.
• A spec-version bump is always documented in CHANGELOG.md and, if it changes the externally observable wire contract, triggers a minor or major release per Semantic Versioning.

Project Structure

srgssr-mcp/├── src/srgssr_mcp/│   ├── __init__.py          # Package│   └── server.py            # MCPServer: 15 tools, OAuth2 client├── .github/│   └── workflows/│       └── ci.yml           # GitHub Actions CI (Python 3.11–3.13)├── pyproject.toml           # Build configuration (hatchling)├── CHANGELOG.md├── CONTRIBUTING.md          # English├── CONTRIBUTING.de.md       # German├── SECURITY.md              # Security policy (English)├── SECURITY.de.md           # Security policy (German)├── LICENSE                  # MIT├── README.md                # This file (English)└── README.de.md             # German version

🛡️ Safety & Limits

Known Limits

• Rate Limits: SRG SSR APIs enforce rate limits — see developer.srgssr.ch for details on the tier of your OAuth2 application
• Data Freshness: EPG data may be delayed by up to 6 hours
• Historical Data: Polis data goes back to 1900 — older data is not available
• Geo-Restriction: Some streaming APIs are only available within Switzerland
• API keys required: SRG SSR APIs require free OAuth2 credentials from developer.srgssr.ch
• Non-commercial use: SRG SSR API terms restrict commercial use without explicit permission from [email protected]
• Weather coverage: SRF Meteo covers Switzerland only

Contributing

See CONTRIBUTING.md (English) · CONTRIBUTING.de.md (German)

Security

For the full security posture, vulnerability reporting process and accepted-risk register, see SECURITY.md (English) · SECURITY.de.md (German). The key egress control is summarised below.

Egress Allowlist

The server implements a code-layer egress allowlist (SEC-021, combined with SEC-004 SSRF defense) to prevent unintended external requests. Every outbound HTTP request is validated by _validate_url_safe() in src/srgssr_mcp/_http.py before it is issued.

Three controls per request:

1. HTTPS-only — http://, file://, ftp:// and other non-HTTPS schemes are rejected.
2. Host allowlist — the URL hostname must equal ALLOWED_HOSTS = {"api.srgssr.ch"} (exact match — subdomain tricks like api.srgssr.ch.attacker.example are blocked). One host covers everything: the OAuth2 token endpoint and every data endpoint.
3. IP blocklist — every resolved IP for the hostname is checked against private, loopback, link-local (incl. 169.254.169.254 cloud-metadata), CGNAT, multicast and reserved ranges (IPv4 + IPv6). Any single match aborts the request — defense-in-depth against DNS rebinding.

Violations surface as ValueError and are mapped to a localized Konfigurationsfehler: … message by _handle_error, so internal network details never leak to the MCP client.

Adding a new SRG SSR domain:

1. Update ALLOWED_HOSTS in src/srgssr_mcp/_http.py.
2. Document the reason in the PR and CHANGELOG.md.
3. Add a positive test case in tests/test_unit.py (mirror test_validate_url_safe_accepts_public_srgssr_host).

Network-Layer Egress (for future SSE/HTTP deployments): see docs/network-egress.md. For the current stdio transport, network-layer controls do not apply — the process runs in the MCP client's user context.

Logging

The server uses structured logging (OBS-003) via structlog with JSON output to stderr — keeping stdout clean for the stdio transport's JSON-RPC traffic.

Format:

• JSON-encoded events, one per line
• ISO 8601 UTC timestamp on every record
• RFC 5424 severity levels: debug, info, notice, warning, error, critical, alert, emergency
• Per-call bound context: tool, business_unit, channel_id, query, etc.

Example output:

{"event": "tool_invoked", "tool": "srgssr_weather_search_location", "query": "Bern", "level": "info", "logger": "mcp.srgssr.weather", "timestamp": "2026-04-30T14:23:45.123Z"}{"event": "tool_succeeded", "tool": "srgssr_weather_search_location", "query": "Bern", "result_count": 3, "matched_variant": "Bern", "level": "info", "logger": "mcp.srgssr.weather", "timestamp": "2026-04-30T14:23:45.456Z"}

Log levels (RFC 5424):

Configuration:

The default level is info. Override via the SRGSSR_LOG_LEVEL environment variable (debug, info, warning, error, critical):

SRGSSR_LOG_LEVEL=debug srgssr-mcp

JSON output is aggregator-friendly — pipe stderr to Datadog, Splunk, Loki, etc., and filter by structured fields (tool, business_unit, level) without regex parsing.

Testing

# Unit tests (no network required)PYTHONPATH=src pytest tests/ -m "not live"
# Integration tests (requires SRG SSR API keys)PYTHONPATH=src pytest tests/ -m "live"
# Lintingruff check src/

Changelog

See CHANGELOG.md

Data Sources & Licenses

All data exposed by this server is fetched live from a single upstream provider, SRG SSR Public API V2 (https://api.srgssr.ch). Every tool return is a typed Pydantic BaseModel that embeds source / license / provenance_url / fetched_at at the top level — so downstream consumers can record the data origin without round-tripping through this README. The SDK exposes the corresponding outputSchema in the tools/list manifest so MCP clients can plan follow-up calls precisely.

Use of the SRG SSR APIs

• Non-commercial use: free, no application required.
• Commercial use: written permission required via [email protected].

This server's MIT license covers the source code only; it does not relicense the upstream data.

License

MIT License — see LICENSE

The SRG SSR APIs used in this project are subject to the SRG SSR Terms of Use.

Author

Hayal Oezkan · github.com/malkreide

Credits & Related Projects

• Data: SRG SSR Developer Portal · SRF Meteo · Polis API
• Protocol: Model Context Protocol – Anthropic / Linux Foundation
• Related:

Synergy example: "What were the results of the 2020 popular votes in Canton Zurich – and how did turnout compare to the national average?" → srgssr-mcp (Polis, cantonal results) + swiss-statistics-mcp (BFS, turnout data)

• Portfolio: Swiss Public Data MCP Portfolio

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