bag-health-mcp

bag-health-mcp

属于 Swiss Public Data MCP Portfolio — 将 AI 模型连接到瑞士公共数据源。

🇩🇪 德语版本

用于获取瑞士公共卫生数据的 MCP 服务。其核心是瑞士联邦公共卫生局（BAG）的传染病仪表板（IDD），提供 51 种病原体的流行病学监测数据（流感、COVID-19、麻疹、污水监测等），并扩展了一个涵盖瑞士卫生观察站（Obsan）、Versorgungsatlas（医疗保健供给地图，含州级时间序列）和 Sucht Schweiz（HBSC 青少年调查）的多源健康指标层。所有数据均为只读的公共开放政府数据。

---

你可以做什么

"Wie ist die aktuelle Grippesituation im Kanton Zürich verglichen mit den letzten Wochen?"
→ bag_health_mcp__get_canton_situation(canton="ZH")

"Gibt es aktuell einen Masernausbruch in der Schweiz?"
→ bag_health_mcp__get_disease_data(series_id="measles/cases/incValue/year", canton="all")

"Wie entwickelt sich das SARS-CoV-2-Signal im Abwasser?"
→ bag_health_mcp__list_series(topic="wastewater_viral_load")
→ bag_health_mcp__get_disease_data(series_id="wastewater_viral_load/NA/value/date", ...)

"Welche Krankheitsdaten stellt das BAG aktuell bereit?"
→ bag_health_mcp__list_diseases()

"Wie hat sich der Alkoholkonsum bei 15-Jährigen seit 2010 entwickelt?"   # 🎯 anchor query
→ bag_health_mcp__search_health_indicators(source="suchtschweiz", topic="alkohol")
→ bag_health_mcp__get_indicator_series(source="suchtschweiz",
      indicator_id="monam/alkoholkonsum-alter-11-15", region="ZH", year_from=2010)
→ More use cases by audience →

🎯 示例查询 — «Wie hat sich der Alkoholkonsum bei 15-Jährigen im Kanton Zürich seit 2010 entwickelt, und wie steht der Kanton im Schweizer Vergleich da?» HBSC 青少年时间序列（通过 Obsan 获取）可显示瑞士全国自 2010 年以来的趋势，并附带 95% 置信区间。该特定指标仅提供全国数据，因此响应中会包含 region_note 说明这一点 （HBSC 不具备州级代表性）。大多数其他 Obsan 指标按州发布——请参阅下文有关分类的说明。这些都是汇总人口统计数据，不构成个人建议。 请参阅 docs/tool-design-health-indicators.md。

---

工具

传染病监测（BAG IDD）：

工具	描述
bag_health_mcp__list_diseases	列出全部 51 个疾病主题，并按类别分组
bag_health_mcp__list_series	列出特定疾病的数据系列
bag_health_mcp__get_series_details	获取可用的筛选维度（州、年龄、性别）
bag_health_mcp__get_disease_data	获取时间序列监测数据
bag_health_mcp__get_canton_situation	查看某个州的情况概览（Schulamt 用例）
bag_health_mcp__list_export_files	列出可用的完整导出数据集
bag_health_mcp__download_export	下载原始 CSV/JSON 导出数据
bag_health_mcp__get_data_version	查看当前数据版本（每周三更新）

健康指标——Obsan、Versorgungsatlas 和 Sucht Schweiz（多来源）：

工具	描述
bag_health_mcp__search_health_indicators	按 source（obsan / versorgungsatlas / suchtschweiz）、主题、地区和年份范围搜索指标
bag_health_mcp__get_indicator_series	获取某项指标的时间序列，说明具体的划分维度（variant：全国 / 按州 / 按年龄组 / 按社会地位 / 分布），并列出其他可用维度。传入 region='ZH' 可获取按州划分的数据；所有数据均附有 95% 置信区间

⚠️ 仅提供汇总人口统计数据。 指标工具提供的是人口层级的汇总数据（按年龄/性别/地区划分的患病率/指标）——不用于个人建议、诊断或个案评估，也不包含个人数据。 这一点已注明在两个工具描述和每条响应（aggregate_statistics_notice）中；对于涉及学校环境中预防主题的 suchtschweiz（HBSC），这一点尤其重要。数据来源：Obsan ind.obsan.admin.ch（清洁的 JSON API）；Sucht Schweiz HBSC 通过 Obsan 镜像提供（全国数据）；Versorgungsatlas 从 Tarifpool 返回按州划分的年度/数值序列（26 个州加上全国总计 CH，附有 95% 置信区间和州与全国的比率）。请参阅各来源的探查说明。

Obsan 会按多个划分维度发布同一指标，而非仅发布一个系列。 在 2026-08-08 对目录中的 60 项进行了测量：50 项有按州划分的数据（kg），49 项有按年龄组划分的数据（ag），24 项有按社会地位划分的数据（sd）——而只有 3 项有普通全国数据（g）。这些是单位不同的不同测量值，因此 get_indicator_series 会在 variant 中注明返回的数据划分维度，并在 variants_available 中列出其他可用维度，而不会将其中一项作为另一项的替代。60 项中有 8 项未发布任何系列；遇到此情况时，会返回失败原因，而非空结果。人口普查记录及日期见 tests/fixtures/obsan_variant_census.json。

工具注解

所有工具均带有 MCP 工具注解，使宿主无需调用工具即可了解其行为。此处的所有工具都相同——只会从公开且列入允许列表的数据来源（BAG IDD、Obsan、Versorgungsatlas）读取数据：

注解	值	含义
readOnlyHint	true	工具不会修改任何状态。
destructiveHint	false	不会产生破坏性副作用。
idempotentHint	true	重复调用不会产生额外影响。
openWorldHint	true	工具会访问外部系统（上游数据 API）。

因此，宿主可以将所有调用视为安全且可缓存的读取操作。这些值在 server.py 中以 READ_ONLY 声明一次，并应用于全部 10 个工具。

MCP 原语

此服务使用全部三种 MCP 原语，并各取所长：

工具（10 个）——实时、带参数的操作，用于调用 IDD API（见上文）。

资源——主机可获取并缓存的静态只读参考数据，无需参数或上游调用：

资源 URI	描述
bag://reference/cantons	工具接受的州代码（包括 FL、all）
bag://reference/disease-categories	按类别划分的疾病主题分类
bag://reference/data-licence	来源、署名和许可条款

提示词——主机可展示的可复用、带参数的工作流（例如作为斜杠命令）：

提示词	参数	用途
canton_situation_brief	canton	起草一份供 Schulamt 使用的公共卫生情况简报
outbreak_check	disease、canton	检查某种疾病当前是否呈上升趋势

实时监测数据由工具提供（数据带参数且每周变化）；固定参考数据通过资源提供；推荐的多工具工作流则封装为提示词。

---

与学校和市政管理部门的相关性

Schulamt / Kreisschulbehörden：

• 监测所在州的流感和 ARI 发病率
• 出现单例麻疹病例时，向疫苗接种率较低的学校发出提醒
• 追踪百日咳，保护未接种疫苗的婴儿（学童的兄弟姐妹）

Stadtverwaltung / KI-Fachgruppe：

• 使用结构化的每周数据开展公共卫生报告
• 将污水监测作为临床病例出现前 1 周的领先指标

与产品组合的协同：

• bag-epl-mcp → “列出了哪些治疗方法？”（EPL 药物数据库）
• bag-health-mcp → “目前正在传播什么？”（监测数据）

---

数据来源

• IDD API：https://api.idd.bag.admin.ch — 无需身份验证
• 更新周期：每周三
• 覆盖范围：瑞士 + 列支敦士登（FL），26 个州
• 主题：51 种病原体，1386 个数据系列

数据来源与许可 / 数据来源与许可

来源	提供方	许可	是否需要署名
传染病仪表板（IDD）	联邦公共卫生局（FOPH / BAG）	opendata.swiss 开放政府数据 — 可免费使用，但须注明来源（瑞士 OGD 条款，相当于 CC BY）	是
健康指标	Obsan — 瑞士健康观察站（ind.obsan.admin.ch）	未明确提供机器可读许可；按瑞士 OGD 惯例处理——可免费使用，须注明各指标来源	是
医疗服务供应图集	Versorgungsatlas（BAG/Obsan，versorgungsatlas.ch）	同上（遵循瑞士 OGD 惯例，注明来源）	是
HBSC 青少年调查	Sucht Schweiz — HBSC，通过 Obsan 镜像获取	同上（遵循瑞士 OGD 惯例，注明「Sucht Schweiz — HBSC」）	是

必需的引用： 联邦公共卫生局 FOPH — 传染病仪表板（IDD），通过 opendata.swiss 提供的开放数据。 对于指标工具，每个响应的 provenance.source 都会注明具体的上游来源（例如通过 Obsan 获取的「Sucht Schweiz — HBSC」）。每个工具响应都在 provenance 区块中包含署名信息（attribution 和 license 字段），以便下游使用方自动展示。

Architecture:
                    ┌─────────────────┐    api.idd.bag.admin.ch (IDD API, no auth)
  MCP Host          │  bag-health-mcp │──▶ ind.obsan.admin.ch   (Obsan JSON API)
  (Claude, etc.) ──▶│  MCP SDK        │──▶ versorgungsatlas.ch  (indicator catalogue)
                    │  10 Tools       │    all HTTPS, egress allow-listed, no auth
                    └─────────────────┘

---

安装

Claude Desktop（stdio）

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

Cloud / HTTP

pip install bag-health-mcp
python -m bag_health_mcp.server --http --port 8000

传输方式、主机和端口通过环境变量设置——MCP_TRANSPORT （http/stdio）、MCP_HOST、MCP_PORT——这是部署时推荐的方式（--http 标志仍可在本地使用）。服务默认绑定到 127.0.0.1，因此本地 HTTP 服务不会暴露到网络。容器和云部署通过显式设置 MCP_HOST=0.0.0.0 来绑定所有接口——提供的 Dockerfile 已这样设置。

⚠️ 安全性： HTTP 传输会将服务暴露到网络。仅在网络隔离环境中绑定到 127.0.0.1 以外的地址——绝不要直接绑定到公共或共享网络。在非本地主机上绑定时，启动时会记录警告。 默认的 stdio 传输不会暴露网络接口。请参阅 docs/security-posture.md。

HTTP 身份验证（可选）： 设置 MCP_AUTH_TOKEN，要求每个 HTTP 请求都携带 Authorization: Bearer <token>（否则返回 401）。未设置 = 不进行身份验证（适用于 stdio/本地）。这限制了谁可以调用该服务；如需真实用户身份，请在其前端接入网关。

CORS（浏览器客户端）： 将 MCP_CORS_ORIGINS 设置为以逗号分隔的来源允许列表，以启用浏览器跨域访问。2026-07-28 路由 标头（Mcp-Method、Mcp-Name、Mcp-Protocol-Version）可通过预检请求； 不会暴露会话标头，因为服务不会签发会话标头。留空 = 不允许跨域（绝不使用通配符）。

主机允许列表（DNS 重绑定）： 将 MCP_ALLOWED_HOSTS 设置为以逗号分隔的列表，列出此服务可通过其访问的名称，包含端口，例如 bag.example.ch:8000。通过任何其他 Host 发出的请求都会被拒绝， 并返回 421；环回地址仍然允许，以便容器健康检查继续正常工作。

在非本地主机绑定时，如果未设置此项，则会关闭检查并记录警告——这适用于由网关置于前端的部署，此时由网关验证 Host。这里不会猜测：在 0.0.0.0 上无法确定可访问的名称，而错误的猜测会拒绝它原本要保护的部署。

这与 MCP_AUTH_TOKEN 相互独立。令牌说明谁在发出请求；此项说明服务通过哪个名称访问。重绑定攻击发生在已持有令牌的浏览器中。

如需大规模运行（无需会话亲和性、资源限制、MCP 网关），请参阅 部署与扩展指南以及 deploy/ 中的参考清单。

日志记录： 服务会将结构化 JSON 日志（每行一个对象，带有 RFC 5424 严重性级别）输出到标准错误——标准输出保留给 stdio JSON-RPC 传输。使用 MCP_LOG_LEVEL 设置级别（默认值为 INFO）。

追踪（可选）： 安装遥测附加组件，并将服务指向 OTLP 收集器，即可获取每次工具调用对应的 OpenTelemetry span，以及经过检测的出站 HTTP：

pip install "bag-health-mcp[telemetry]"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
# optional: OTEL_SERVICE_NAME=bag-health-mcp

除非同时安装了附加组件并设置了 OTEL_* 端点，否则追踪不会执行任何操作。Span 仅携带工具名称，以及（出错时）异常类——绝不包含工具参数、州或监控数据。

---

可用疾病主题

类别	主题
呼吸道	influenza, covid19, acute_respiratory_infection, respiratory_pathogens
肠道传染病	campylobacteriosis, salmonellosis, ehec, listeriosis, hepatitis_a/e
性传播与血源性疾病	hiv, aids, syphilis, gonorrhea, hepatitis_b/c, chlamydiosis
疫苗可预防疾病	measles, pertussis, rubella, tetanus, diphtheria, ipd, meningo
虫媒传染病	lyme_borreliosis, tick-borne_encephalitis, dengue, malaria, zika
污水	wastewater_viral_load, wastewater_sequencing

---

演示

Claude 询问苏黎世州的流感情况——一次工具调用、结构化结果，以及可供采取行动的德语摘要。

---

MCP 协议版本

此服务原生支持 MCP 2026-07-28，并通过同一端点继续为所有旧版客户端提供服务。连接上的第一个请求决定客户端所属的时代；之后若声明属于另一个时代，则会被拒绝。

时代	修订版本	使用方
每请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求。无需 initialize，也无需会话——SDK 自带的 Client 默认会连接到这里。
initialize 握手	2024-11-05 … 2025-11-25	尚不支持 2026-07-28 的客户端。服务器会以请求指定的修订版本作答；如果请求要求更新的版本，则以 2025-11-25 为上限。

本文所说的“原生支持”，具体含义如下，每一点均由 tests/test_spec_2026_07_28.py 中的测试验证：

• 两个时代都无需会话。 响应中不会携带 Mcp-Session-Id；任何副本都可以响应任何请求，因此使用普通的轮询负载均衡器即可（参见部署与扩展）。对于握手客户端，这是刻意设置的 stateless_http=True。
• 不使用已弃用的能力。 在 2026-07-28 中，协议日志（ctx.info/ctx.warning）、采样和根目录均已弃用（SEP-2577）。服务器不会使用这些功能；运行日志会写入 stderr。测试套件会将 MCPDeprecationWarning 视为错误，因此任何重新引入的调用都会导致 CI 失败。
• 不会向客户端发送请求。 没有工具会向客户端询问任何内容，因此不依赖 2026-07-28 中已移除的反向通道。
• 进度（服务器向客户端发送，仍包含在规范中）在两个时代都会通过工具调用的响应流传送。
• 缓存提示（ttlMs/cacheScope，SEP-2549）适用于列表方法；CORS 适用于路由标头 Mcp-Method、Mcp-Name、Mcp-Protocol-Version。

两个修订版本都在 tests/test_protocol_version.py 中固定，并与已安装的 SDK 进行断言，因此 Dependabot 升级 mcp 时不会悄然更改任一版本。握手上限通过已组装的 ASGI 堆栈运行实时 initialize 测得，而不是从常量名称推断。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——若仅以它为依据固定版本，握手时代仍可能发生漂移。

更新策略。 门禁检查失败时，不要盲目编辑常量：阅读两个修订版本之间的规范变更日志，验证服务器行为仍然正常，然后一并更新常量、本节、README.de.md 和 CHANGELOG.md。

---

安全与限制

方面	详情
访问	只读——无法执行写入操作
出站访问	代码层允许列表：服务器只会联系三个公共数据主机（api.idd.bag.admin.ch、ind.obsan.admin.ch、www.versorgungsatlas.ch），仅限 HTTPS，并在每个请求（包括重定向跳转）中强制执行（SSRF/SEC-004 + SEC-021）。网络层配套策略见 deploy/networkpolicy.yaml
个人数据	无——所有来源的数据均已汇总/匿名化（法律要求 BAG IDD 数据按州汇总；指标按年龄/性别/地区汇总人口数据）
速率限制	IDD API 未公布速率限制；服务器默认将每次调用的响应限制为 104 个数据点（limit_weeks 参数）
超时	每次 API 调用 30 s
身份验证	无需 API 密钥——所有数据均可公开访问
数据许可	opendata.swiss OGD——可免费使用，但必须注明来源（等同于 CC BY）。必须引用 FOPH IDD；参见数据来源与许可
服务条款	受 BAG IDD API 服务条款约束

---

已知限制

• Beta API：IDD API 标记为 v0.1 beta——架构可能会在不另行通知的情况下变更
• 每周更新：数据并非实时数据；仅于每周三更新
• 州级粒度：部分罕见病的病例数不足以提供州级数据（为保护隐私而隐藏）
• 年龄组：可用维度因疾病系列而异；使用 bag_health_mcp__get_series_details 查看

---

合规

• ISDS（苏黎世市）： 信息安全保护需求分类草案（Schutzbedarfsanalyse per Grundwert + measures mapping）见 docs/isds-klassifikation.md。这是 一份基于技术依据的草案，尚待 ISBO/OIZ 批准——并非具有约束力的 分类。
• 数据分类（Schulamt）： 数据被分类为公开 / BUI （公共 OGD，不含个人数据，在州级聚合，并在源头抑制小样本单元）。分类方案草案和聚合风险说明见 docs/datenklassifikation-schulamt.md； 执行聚合的 bag_health_mcp__get_canton_situation 工具会在其响应中说明这一点。
• 安全状况： 致命三要素评估（服务严格只读 → 不受影响）、密钥管理决策（无密钥——公开数据）和网络暴露说明见 docs/security-posture.md。
• 阶段架构： 这是一个**第 1 阶段（只读）**服务；写入/发送功能将推迟到满足文档所列前提条件后再启用。参见 docs/roadmap.md。
• 报告漏洞： 如何私下报告安全问题，请参阅安全政策。

---

贡献

参见 CONTRIBUTING.md（德语）。

安全

有关安全状况以及如何保密报告漏洞，请参阅 SECURITY.md（德语）。

许可证

代码： MIT（参见 LICENSE）。

数据： BAG IDD 是 opendata.swiss 上的开放政府数据，采用免费使用但必须注明来源的许可（瑞士 OGD 条款，相当于 CC BY） ——并非公有领域。重新使用数据时，请注明联邦公共卫生局 FOPH（IDD）；参见数据来源与许可证。

作者

Hayal Oezkan · github.com/malkreide

相关作品中的服务

• swiss-statistics-mcp — BFS 人口统计数据
• bag-epl-mcp — BAG 药品报销清单
• zurich-opendata-mcp — 苏黎世市开放数据

安装

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

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