srgssr-mcp

🇨🇭 属于 瑞士公共数据 MCP 组合

📺 srgssr-mcp

连接 AI 模型与 SRG SSR 公共 API 的 MCP 服务——天气、电视／广播元数据、节目指南，以及自 1900 年以来的瑞士公投／选举数据（SRF、RTS、RSI、RTR、SWI）。

🇩🇪 德语版

---

概述

srgssr-mcp 让 Claude 等 AI 助手能够直接访问 SRG SSR 的公共 API——瑞士的国家公共广播机构。天气预报、电视和广播元数据、电子节目指南，以及历史民主数据（自 1900 年以来的公投和选举），都可以通过一个标准化的 MCP 接口访问。

该服务涵盖五个主题类别：SRF 天气、视频、音频、EPG 和 Polis（瑞士民主）。每个类别都对应一组专用工具，可将原始 SRG SSR API 数据转换为简洁的 JSON 响应。

演示示例查询： “倡议 X 的公投在苏黎世有哪些州级结果？”——回答基于 Polis 系统的历史实时数据，而非幻觉。

---

功能

• 🌦️ 天气——地点搜索、当前天气状况、24 小时逐小时预报、7 天预报（SRF Meteo）
• 📺 视频——电视节目列表、最新剧集、所有业务部门的电视频道直播
• 🎙️ 音频——广播节目列表、音频剧集、电台直播
• 📅 EPG——任意电视频道或广播频道的每日节目安排
• 🗳️ Polis——自 1900 年以来的公投和选举，全国及州级结果
• 🏢 多业务部门——SRF（DE）、RTS（FR）、RSI（IT）、RTR（RM）、SWI（多语言）
• 🔐 OAuth2——通过 Client Credentials 流自动管理令牌
• ☁️ 双传输方式——供 Claude Desktop 使用的 stdio，以及用于云端部署的 Streamable HTTP/SSE

---

前提条件

• Python 3.11+
• 来自 developer.srgssr.ch 的 API 密钥（免费注册）：
  1. 创建账户并登录
  2. 在“My Apps”下创建新应用
  3. 添加产品 SRG SSR PUBLIC API V2
  4. 记下你的 Consumer Key 和 Consumer Secret

⚠️ 使用条款： SRG SSR API 可用于非商业用途。如需商业使用，请直接联系 [email protected]。

---

安装

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

# Install
pip install -e .

或使用 uvx（无需永久安装）：

uvx srgssr-mcp

或通过 pip 安装：

pip install srgssr-mcp

---

快速开始

# 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

立即在 Claude Desktop 中试用：

“明天苏黎世的天气怎么样？” “今晚 SRF 1 有什么节目？” “2010 年至 2020 年间，伯尔尼州举行过哪些公投？”

---

配置

Claude Desktop

最简配置（推荐）：

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

配置文件位置：

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

保存后，请完全重启 Claude Desktop。

其他 MCP 客户端

兼容 Cursor、Windsurf、VS Code + Continue、LibreChat、Cline，以及通过 mcp-proxy 使用的可自托管模型。设置相同的环境变量。

云端部署（用于浏览器访问的 SSE）

用于通过浏览器中的 claude.ai 访问（例如，在没有本地软件的受管工作站上）：

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

传输方式、主机、端口和挂载路径均由环境变量控制 （参见 srgssr_mcp.server.Settings）。SRGSSR_MCP_TRANSPORT 的有效值为 stdio（默认值）、sse 和 streamable-http。

💡 “开发者笔记本用 stdio，浏览器用 SSE。”

---

MCP 原语

此服务提供了 MCP 的全部三种正交原语：

原语	理解方式	内容
工具（动词）	可执行函数／参数化查询	15 个工具——搜索、列出、获取、汇总
资源（名词）	可通过 URI 访问、适合缓存的被动数据	EPG 条目和不可变的投票结果
提示词（方案）	可复用的工作流模板	投票分析和每日简报

工具涵盖参数化搜索（年份范围、自由文本、分页列表），每次调用都可能产生不同结果。资源提供稳定的数据点，适合安全缓存：指定频道和日期已发布的 EPG，或已结束的瑞士全民投票最终结果。提示词将重复进行的多步骤分析标准化，用户无需每次从头描述。

资源

URI 模板	说明
epg://{bu}/{channel_id}/{date}	SRF、RTS、RSI 的每日电视／广播节目指南（例如 epg://srf/srf-1/2026-04-30）
votation://{votation_id}	已结束的瑞士全民投票详细结果（例如 votation://v1）

EPG 电台 ID——使用连字符，与直播流 ID 不同：

业务部门	电视	广播
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

提示词

名称	参数	用途
analyse_abstimmungsverhalten	votation_id、focus（stadt_land／sprachregionen／kantone）	对瑞士全民投票进行结构化分析
tagesbriefing_kanton	location、channel_id、business_unit、date	结合天气和 EPG 的每日简报

---

可用工具

工具命名约定

此服务的工具名称采用 snake_case，遵循 Python 生态惯例。虽然 MCP 最佳实践倾向于使用 camelCase，以便大模型更好地进行词元化，但 snake_case 仍然是可接受的，也能让工具名称与底层 Python 函数标识符保持一致。

所有工具均遵循 srgssr_<domain>_<action> 模式，使用命名空间前缀 srgssr_ 和语义明确的 <domain>_<action> 后缀（例如 srgssr_weather_current、srgssr_polis_get_votations）。

🌦️ SRF 天气（4 个工具）

工具	说明	数据来源
srgssr_weather_search_location	按名称或邮政编码搜索地点，以获取 geolocationId	SRF Meteo
srgssr_weather_current	瑞士地点的当前天气状况	SRF Meteo
srgssr_weather_forecast_24h	24 小时逐小时预报	SRF Meteo
srgssr_weather_forecast_7day	7 天逐日预报	SRF Meteo

📺 视频（3 个工具）

工具	说明	数据来源
srgssr_video_get_shows	列出某业务部门的电视节目（character_filter 取 a–z/# 可选择一个首字母；省略则遍历全部 27 个）	SRG SSR IL
srgssr_video_get_episodes	获取某节目的最新剧集	SRG SSR IL
srgssr_video_get_livestreams	列出电视直播频道	SRG SSR IL

🎙️ 音频（3 个工具）

工具	描述	数据来源
srgssr_audio_get_shows	列出一个广播频道的节目（必须提供 channel_id——v2 API 不支持按业务单元列出节目）	SRG SSR IL
srgssr_audio_get_episodes	获取某个节目的音频剧集	SRG SSR IL
srgssr_audio_get_livestreams	列出正在直播的广播电台	SRG SSR IL

📅 EPG – 电子节目指南（1 个工具）

工具	描述	数据来源
srgssr_epg_get_programs	电视频道或广播频道的每日节目安排	SRG SSR IL

🗳️ Polis – 瑞士民主（3 个工具）

工具	描述	数据来源
srgssr_polis_get_votations	1900 年以来的全民投票（国家级或州级）	Polis API
srgssr_polis_get_votation_results	某项投票的详细结果	Polis API
srgssr_polis_get_elections	1900 年以来的选举结果	Polis API

支持的业务单元

代码	单元	语言
srf	SRF (Schweizer Radio und Fernsehen)	德语
rts	RTS (Radio Télévision Suisse)	法语
rsi	RSI (Radiotelevisione svizzera)	意大利语
rtr	RTR (Radiotelevisiun Svizra Rumantscha)	罗曼什语
swi	SWI swissinfo.ch	多语言

示例用例

查询	工具
“明天苏黎世的天气怎么样？”	srgssr_weather_forecast_24h
“今晚 SRF 1 播什么？”	srgssr_epg_get_programs
“最新的 Tagesschau 剧集有哪些？”	srgssr_video_get_episodes
“2010–2020 年伯尔尼州的全民投票有哪些？”	srgssr_polis_get_votations
“口罩倡议投票的州级结果是什么？”	srgssr_polis_get_votation_results
“RTS 当前播出的所有广播节目有哪些？”	srgssr_audio_get_livestreams → srgssr_audio_get_shows

→ 按受众查看更多用例 →

---

架构

┌─────────────┐
│ 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│
└─────────────────────┘

数据来源

来源	数据	访问方式
developer.srgssr.ch	SRG SSR PUBLIC API V2（天气、A/V、EPG、Polis）	OAuth2（免费注册）

署名： SRG SSR API 受 SRG SSR 使用条款约束。

---

开发阶段

此服务处于 阶段 1：只读封装。

此服务仅针对 SRG SSR 公共 API 提供 GET 类操作。按照设计，不具备写入、修改或删除功能——有关威胁模型的影响，请参阅安全与限制。

阶段 1 完成标准

• 五个主题类别（天气、视频、音频、EPG、Polis）共 14 个只读工具
• 使用令牌缓存的 OAuth2 Client Credentials 身份验证
• 双语文档（EN/DE）
• 测试套件（单元测试 + 实时测试）——参阅 OPS-001
• 结构化日志记录——参阅 OBS-003 和 CHANGELOG
• 可用于生产环境的错误处理（统一重试/退避策略、类型化错误封装）

后续阶段

• **阶段 2（写入）：**未列入计划。 SRG SSR 公共 API 按约定仅支持只读；上游没有可供写入的接口。
• **阶段 3（多 Agent）：**暂缓评估。 待用户反馈表明存在此服务应协调的具体多 Agent 工作流后，再重新考虑（例如，与 swiss-statistics-mcp 或 swiss-transport-mcp 进行跨服务聚合）。

---

MCP 协议版本

mcp 2.x 在同一服务器上支持两个协议时代，客户端在连接上发送的第一个请求决定使用哪一个：

时代	版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当今客户端使用的协议。服务器会返回请求中指定的版本；如果请求的版本更新，则返回上限 2025-11-25。
逐请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会建立现代连接。

src/srgssr_mcp/_app.py 中的 PROTOCOL_VERSION 指定了现代时代的版本。它会在导入时根据已安装 SDK 的 SUPPORTED_PROTOCOL_VERSIONS 进行验证——但该列表向后兼容，仍包含 2024-11-05，因此成员检查只能捕获某个版本被移除，无法发现版本不一致。tests/test_protocol_version.py 会针对 SDK 检查这两个时代的版本，并负责捕获版本不一致。版本升级会记录在对应版本的 CHANGELOG.md 中。

服务器实际上在线路上发送的内容

上表曾是依据 SDK 常量作出的断言。现在，tests/test_spec_2026_07_28.py 会通过 httpx.ASGITransport 将真实请求发送到 MCPServer.streamable_http_app()，并验证两个时代的响应。该实测验证了以下内容：

属性	线路上的表现
现代入口	server/discover，没有 initialize，也没有 Mcp-Session-Id；supportedVersions: ["2026-07-28"]
握手版本上限	客户端通过 initialize 请求 2026-07-28 时，会收到 2025-11-25——这是实测结果，并非推断
服务器身份	io.modelcontextprotocol/serverInfo 随每个现代响应一起置于 _meta 中，并携带已安装的软件包版本
新鲜度（SEP-2549）	server/discover 和四种列表方法的 ttlMs: 300000、cacheScope: public
工具显示名称	根据 BaseMetadata 设置 title，并同步到 annotations.title，供只读取此处的握手时代客户端使用
2026-07-28 中已撤销	ping、logging/setLevel、resources/subscribe、resources/unsubscribe 和 tasks/* 均返回 -32601
日志记录能力	不声明，也不使用：SEP-2577 自 2026-07-28 起弃用该能力，而且该版本中的日志传递是逐请求选择加入，服务器不得默认启用。工具活动会通过 structlog 输出到 stderr——参见 src/srgssr_mcp/tools/__init__.py

这项实测在首次运行时就证明了其价值：当时有 425 项测试通过，覆盖率为 96%，但 serverInfo.version 是空字符串；每个 tools/call 都返回 isError（FastMCP 1.x 的 ctx.info(msg, **kwargs) 调用形式会被 mcp 2.x 拒绝）；还有八个工具无法接受其自身已发布的 inputSchema 所声明的枚举字符串（ConfigDict(strict=True) 要求传入枚举实例，而 JSON 负载无法携带这种实例）。这些问题在进程内部都不可见——这正是测试线路数据的全部意义。

更新政策

• SDK 依赖更新通过 Dependabot 提交（.github/dependabot.yml，每月执行，按 mcp-sdk 标签分组），并在合并前运行完整测试套件。
• 在功能分支上，针对相关的 MCP SDK 版本评估规范升级；MCP 官方变更日志 是破坏性变更的权威来源。
• 规范版本升级始终记录在 CHANGELOG.md 中；如果它会改变外部可观察到的线路契约，则根据 语义化版本 发布次要版本或主要版本。

---

项目结构

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

---

🛡️ 安全与限制

方面	详情
访问权限	只读 — 服务仅从 SRG SSR API 读取数据，无法发布、修改或删除任何内容
个人数据	不涉及个人数据 — 所有端点均提供公开的广播元数据、天气观测数据以及历史投票／选举结果
速率限制	受 developer.srgssr.ch 上 OAuth2 应用的等级限制；服务还会为每次查询设置合理的上限（例如，每次列表调用最多 100 个剧集、50 个节目）
超时	每次上游 API 调用 30 秒
身份验证	OAuth2 客户端凭据（免费注册）；密钥保存在本地，绝不记录到日志中
许可与使用	SRG SSR API 仅限非商业用途；商业用途需获得 [email protected] 的书面许可
服务条款	受 SRG SSR Developer Terms of Use 约束 — 用户仍需自行负责署名并遵守相关规定

---

已知限制

• 速率限制： SRG SSR API 设有速率限制 — 有关 OAuth2 应用等级的详情，请参阅 developer.srgssr.ch
• 数据时效性： EPG 数据可能延迟最多 6 小时
• 历史数据： Polis 数据可追溯至 1900 年 — 不提供更早的数据
• 地理限制： 部分流媒体 API 仅在瑞士境内可用
• 需要 API 密钥： SRG SSR API 需要从 developer.srgssr.ch 免费获取 OAuth2 凭据
• 非商业用途： 未经 [email protected] 明确许可，SRG SSR API 条款禁止商业用途
• 天气覆盖范围： SRF Meteo 仅覆盖瑞士

---

贡献

参阅 CONTRIBUTING.md（英语）· CONTRIBUTING.de.md（德语）

---

安全

有关完整的安全状况、漏洞报告流程以及已接受风险登记表，请参阅 SECURITY.md（英语）· SECURITY.de.md（德语）。 以下概述了关键的出站流量控制措施。

出站流量允许列表

服务实施了代码层出站流量允许列表（SEC-021，结合 SEC-004 SSRF 防护），以防止意外的外部请求。每个出站 HTTP 请求在发出前，都会由 src/srgssr_mcp/_http.py 中的 _validate_url_safe() 进行验证。

每个请求的三项控制措施：

1. 仅限 HTTPS — 拒绝 http://、file://、ftp:// 及其他非 HTTPS 协议。
2. 主机允许列表 — URL 主机名必须与 ALLOWED_HOSTS = {"api.srgssr.ch"} 完全相同（精确匹配 — 会拦截 api.srgssr.ch.attacker.example 等子域名伪装）。单个主机即可涵盖所有内容：OAuth2 令牌端点和所有数据端点。
3. IP 阻止列表 — 检查该主机名解析出的每个 IP，确保其不属于私有、环回、链路本地（包括 169.254.169.254 云元数据）、CGNAT、多播和保留地址范围（IPv4 + IPv6）。任何一个地址匹配都会中止请求 — 以纵深防御应对 DNS 重绑定攻击。

违规会触发 ValueError，并由 _handle_error 转换为本地化的 Konfigurationsfehler: … 消息，因此内部网络详情绝不会泄露给 MCP 客户端。

添加新的 SRG SSR 域名：

1. 更新 src/srgssr_mcp/_http.py 中的 ALLOWED_HOSTS。
2. 在 PR 和 CHANGELOG.md 中说明原因。
3. 在 tests/test_unit.py 中添加正向测试用例（参照 test_validate_url_safe_accepts_public_srgssr_host）。

**网络层出站流量（适用于未来的 SSE/HTTP 部署）：**参阅 docs/network-egress.md。对于当前的 stdio 传输方式，网络层控制不适用 — 进程在 MCP 客户端的用户上下文中运行。

---

日志记录

服务器通过 structlog 使用结构化日志记录（OBS-003），并以 JSON 格式输出到 stderr — 让 stdout 保持干净，以便 stdio 传输承载 JSON-RPC 流量。

格式：

• 每行一条 JSON 编码的事件
• 每条记录都包含 ISO 8601 UTC timestamp
• RFC 5424 严重性级别：debug、info、notice、warning、error、critical、alert、emergency
• 每次调用绑定的上下文：tool、business_unit、channel_id、query 等

输出示例：

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

日志级别（RFC 5424）：

级别	用途
debug	OAuth 令牌缓存命中、内部状态
info	工具调用、成功响应、服务器生命周期
warning	可恢复的情况（即将触及速率限制、不受支持的业务单元）
error	API 故障、超时（可恢复）
critical	凭据问题、服务降级

配置：

默认级别为 info。可通过 SRGSSR_LOG_LEVEL 环境变量覆盖（debug、info、warning、error、critical）：

SRGSSR_LOG_LEVEL=debug srgssr-mcp

JSON 输出便于聚合 — 将 stderr 管道传输到 Datadog、Splunk、Loki 等，并按结构化字段（tool、business_unit、level）筛选，无需使用正则表达式解析。

---

测试

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

# Linting
ruff check src/

---

更新日志

请参阅 CHANGELOG.md

---

数据来源与许可证

此服务公开的所有数据都从单一上游提供方实时获取，即 SRG SSR Public API V2（https://api.srgssr.ch）。每个工具的返回值都是一个带类型的 Pydantic BaseModel，在顶层包含 source / license / provenance_url / fetched_at — 因此下游使用方无需往返查阅本 README，即可记录数据来源。SDK 会在 tools/list 清单中公开相应的 outputSchema，以便 MCP 客户端精确规划后续调用。

集群	提供方	许可证	备注
天气	SRF Meteo（api.srgssr.ch）	SRG SSR Terms of Use	地理范围仅限瑞士
视频 / 音频 / EPG	SRF · RTS · RSI · RTR · SWI	SRG SSR Terms of Use	仅提供元数据 — 不再分发流媒体 URL
Polis（投票 / 选举）	SRG SSR Polis	SRG SSR Terms of Use	历史数据始于 1900 年

SRG SSR API 的使用

• 非商业用途：免费，无需申请。
• 商业用途：需通过 [email protected] 获取书面许可。

本服务的 MIT 许可证仅涵盖源代码；不会更改上游数据的许可。

---

许可证

MIT License — 请参阅 LICENSE

本项目使用的 SRG SSR API 受 SRG SSR Terms of Use 约束。

---

作者

Hayal Oezkan · github.com/malkreide

---

致谢与相关项目

• 数据：SRG SSR Developer Portal · SRF Meteo · Polis API
• 协议：Model Context Protocol – Anthropic / Linux Foundation
• 相关项目：

服务	描述
zurich-opendata-mcp	苏黎世市开放数据（OSTLUFT 空气质量、天气、停车、地理数据）
swiss-transport-mcp	瑞士公共交通——OJP 2.0 行程规划、SIRI-SX 运行中断信息
swiss-environment-mcp	BAFU 环境数据——空气质量、水文、自然灾害
swiss-statistics-mcp	BFS STAT-TAB——682 个统计数据集
fedlex-mcp	通过 Fedlex SPARQL 获取瑞士联邦法律

协同示例： “苏黎世州 2020 年全民投票的结果是什么？投票率与全国平均水平相比如何？” → srgssr-mcp（Polis，州级结果）+ swiss-statistics-mcp（BFS，投票率数据）

• 项目集：Swiss Public Data MCP Portfolio

安装

通过 uv 的 uvx 运行——无需克隆或手动安装。将其添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

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