srgssr-mcp

> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**

# 📺 srgssr-mcp

![Version](https://img.shields.io/badge/version-2.0.1-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![CI](https://github.com/malkreide/srgssr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/malkreide/srgssr-mcp/actions)
[![Data Source](https://img.shields.io/badge/Data-SRG%20SSR%20Public%20API-red)](https://developer.srgssr.ch)

> 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](README.de.md)

<p align="center">
  <img src="assets/demo.svg" alt="Demo: Claude asks a question → srgssr-mcp tool call → grounded answer from SRG SSR Polis API" width="760">
</p>

---

## 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](https://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 [api@srgssr.ch](mailto:api@srgssr.ch) directly.

---

## Installation

```bash
# Clone the repository
git clone https://github.com/malkreide/srgssr-mcp.git
cd srgssr-mcp

# Install
pip install -e .
```

Or with `uvx` (no permanent installation):

```bash
uvx srgssr-mcp
```

Or via pip:

```bash
pip install srgssr-mcp
```

---

## Quickstart

```bash
# Set credentials
export 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):**

```json
{
  "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):

```bash
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:

| Primitive | Mental model | What's here |
|---|---|---|
| **Tools** (verbs) | Executable functions / parametrized queries | 15 tools — search, list, fetch, aggregate |
| **Resources** (nouns) | Cache-friendly passive data behind URIs | EPG entries and immutable votation results |
| **Prompts** (recipes) | Reusable workflow templates | Voting analysis & daily briefing |

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

| URI template | Description |
|---|---|
| `epg://{bu}/{channel_id}/{date}` | Daily TV/radio program guide for SRF, RTS, RSI (e.g. `epg://srf/srf-1/2026-04-30`) |
| `votation://{votation_id}` | Detailed result of a closed Swiss popular vote (e.g. `votation://v1`) |

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

| Business unit | TV | Radio |
|---|---|---|
| SRF | `srf-1`, `srf-2`, `srf-info` | `srf-1`, `srf-2`, `srf-2-kultur`, `srf-3`, `srf-4`, `srf-musikwelle`, `srf-virus` |
| RTS | `rts-1`, `rts-2`, `rts-info` | `LA1ERE`, `ESPACE2`, `COULEUR3`, `OPTION_MUSIQUE` |
| RSI | `la-1`, `la-2` | `rete-uno`, `rete-due`, `rete-tre` |


### Prompts

| Name | Arguments | Purpose |
|---|---|---|
| `analyse_abstimmungsverhalten` | `votation_id`, `focus` (`stadt_land` / `sprachregionen` / `kantone`) | Structured analysis of a Swiss popular vote |
| `tagesbriefing_kanton` | `location`, `channel_id`, `business_unit`, `date` | Daily briefing combining weather and EPG |

---

## 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)

| Tool | Description | Data Source |
|---|---|---|
| `srgssr_weather_search_location` | Search for a location by name or postal code to obtain a `geolocationId` | SRF Meteo |
| `srgssr_weather_current` | Current weather conditions for a Swiss location | SRF Meteo |
| `srgssr_weather_forecast_24h` | Hourly 24-hour forecast | SRF Meteo |
| `srgssr_weather_forecast_7day` | Daily 7-day forecast | SRF Meteo |

### 📺 Video (3 tools)

| Tool | Description | Data Source |
|---|---|---|
| `srgssr_video_get_shows` | List TV shows for a business unit (`character_filter` a–z/# selects one initial; omit it to fan out over all 27) | SRG SSR IL |
| `srgssr_video_get_episodes` | Retrieve latest episodes of a show | SRG SSR IL |
| `srgssr_video_get_livestreams` | List live TV channels | SRG SSR IL |

### 🎙️ Audio (3 tools)

| Tool | Description | Data Source |
|---|---|---|
| `srgssr_audio_get_shows` | List radio shows for one radio channel (`channel_id` required — the v2 API has no per-unit listing) | SRG SSR IL |
| `srgssr_audio_get_episodes` | Retrieve audio episodes of a show | SRG SSR IL |
| `srgssr_audio_get_livestreams` | List live radio stations | SRG SSR IL |

### 📅 EPG – Electronic Program Guide (1 tool)

| Tool | Description | Data Source |
|---|---|---|
| `srgssr_epg_get_programs` | Daily program schedule for a TV or radio channel | SRG SSR IL |

### 🗳️ Polis – Swiss Democracy (3 tools)

| Tool | Description | Data Source |
|---|---|---|
| `srgssr_polis_get_votations` | Popular votes since 1900 (national or cantonal) | Polis API |
| `srgssr_polis_get_votation_results` | Detailed results of a specific vote | Polis API |
| `srgssr_polis_get_elections` | Election results since 1900 | Polis API |

### Supported Business Units

| Code | Unit | Language |
|---|---|---|
| `srf` | SRF (Schweizer Radio und Fernsehen) | German |
| `rts` | RTS (Radio Télévision Suisse) | French |
| `rsi` | RSI (Radiotelevisione svizzera) | Italian |
| `rtr` | RTR (Radiotelevisiun Svizra Rumantscha) | Romansh |
| `swi` | SWI swissinfo.ch | Multilingual |

### Example Use Cases

| Query | Tool |
|---|---|
| *"Weather in Zurich tomorrow?"* | `srgssr_weather_forecast_24h` |
| *"What's on SRF 1 tonight?"* | `srgssr_epg_get_programs` |
| *"Latest Tagesschau episodes?"* | `srgssr_video_get_episodes` |
| *"Popular votes in Canton Bern 2010–2020?"* | `srgssr_polis_get_votations` |
| *"Cantonal results of the mask initiative vote?"* | `srgssr_polis_get_votation_results` |
| *"All current RTS radio shows?"* | `srgssr_audio_get_livestreams` → `srgssr_