seco-labor-mcp

🇨🇭 属于 Swiss Public Data MCP Portfolio

SECO 劳动力市场 MCP 服务

🌐 英语 | 德语

一个 MCP（Model Context Protocol）服务，通过 opendata.swiss 提供来自 SECO（Staatssekretariat für Wirtschaft）和 AMSTAT 的瑞士劳动力市场数据。

---

概述

此服务将 AI 模型连接到瑞士劳动力市场统计数据——失业率、求职者、空缺职位、青年失业情况和职业分类明细——全程无需 API 密钥。

主要受众：

• 🏫 教育局 / 教育规划 — 青年失业情况、职业指导数据
• 📊 研究与分析 — 劳动力市场趋势、各州比较
• 🤖 AI Agent — 自动监控并报告劳动力市场情况

典型查询：
"苏黎世州哪些职业群体的青年失业率最高？哪些学徒职业受职位申报义务约束？" → 按受众查看更多用例 →

---

数据来源（阶段 1 — 无需身份验证）

来源	说明	状态
opendata.swiss	CKAN 目录；固定使用的 BFS 表格 T3.3.0.1 包含 SECO 年度序列	✅ 在线
arbeit.swiss	月度新闻稿（PDF，结构化 URL 模式）	✅ 在线
amstat.ch	AMSTAT 参考门户	⚠️ JavaScript 单页应用，无公开 REST API
unfallstatistik.ch	Unfallstatistik UVG（SSUV/KSUV c/o Suva）——职业事故和疾病	⚠️ 仅提供 PDF，无 API（见下文）

---

架构

┌─────────────────────────────────────────────────────┐
│                  seco-labor-mcp                     │
│                                                     │
│  ┌─────────────┐    ┌──────────────────────────┐   │
│  │  FastMCP    │    │      9 MCP Tools         │   │
│  │  Server     │◄──►│  seco_search_datasets    │   │
│  │  (stdio /   │    │  seco_get_dataset        │   │
│  │   HTTP)     │    │  seco_get_unemployment_* │   │
│  └─────────────┘    │  seco_get_youth_*        │   │
│         │           │  seco_get_job_seekers    │   │
│         ▼           │  seco_get_open_positions │   │
│  ┌─────────────┐    │  seco_get_monthly_url    │   │
│  │  httpx      │    │  seco_list_cantons       │   │
│  │  async      │    └──────────────────────────┘   │
│  └──────┬──────┘                                   │
└─────────┼───────────────────────────────────────────┘
          │
          ▼
  ┌───────────────────────────────────┐
  │  opendata.swiss CKAN API          │
  │  https://opendata.swiss/api/3/    │
  │  action/package_search            │
  │  action/package_show              │
  └───────────┬───────────────────────┘
              │
              ▼
  ┌───────────────────────────────────┐
  │  SECO Data Resources              │
  │  CSV / XLSX / PDF Downloads       │
  │  (monthly labor market data)      │
  └───────────────────────────────────┘

---

数据来源与缺失内容

SECO 已不再是 opendata.swiss 上的数据发布方。 已于 2026-08-14 核实： organization_show 返回 404，且 organization_list 中的 176 条记录里没有 SECO。在此之前，服务会筛选该组织的所有搜索结果，因此返回空结果——组织名称查找失败，看起来就像搜索结果为空。

登记失业者和求职者数据仍由 SECO 提供：BFS 在表格 T3.3.0.1 中发布这些数据，并在页脚注明 SECO。服务通过固定的数据集 ID（sources.py）读取该表，并通过在线测试与实时来源进行核验。

系列	2000	2025
登记求职者（SECO）	124.6	214.1
登记失业者（SECO）	72.0	133.7
ILO 失业者（BFS）	126.5	248.5

千人，年平均值

这三个系列衡量的内容并不相同：2000 年，ILO 数据是登记数据的 1.76 倍。服务会将它们分别标注并报告，绝不会将其中一个换算成另一个。

州级数据：四个州，四种架构

没有全国月度序列——但四个州会发布各自的 RAV 数据，每个州都有自己的门户和列名。对于这些州，seco_get_unemployment_overview(canton=…) 会返回实际数据：

州	粒度	起始时间	层级	备注
TG	月度	2016-01	州	仅有按年龄组划分的序列 → 青年失业人数
FR	月度	2004-01	州和瑞士	包含全国月度数据，作为对照行
ZG	月度	1993-01	州	青年失业数据仅提供比率，不提供人数
ZH	年度	1991	市镇	没有月度数据；区和地区与市镇位于同一列中，并会单独区分

其余 22 个州会收到明确的拒绝响应——既不会返回其他州的数据，也不会返回全国汇总数据。看似完整的部分覆盖，比没有数据更糟。

这四个序列彼此不可比较，也无法汇总为瑞士数据：时间轴不同、地理层级不同，而且 ZG 提供的是比率而非人数。

仍不可用的数据：按职业组划分的失业数据、全国空缺职位序列，以及瑞士全国或 26 个州中 24 个州的青年失业数据。相关工具会说明这一点，且不会返回替代数据。这些数据可在 amstat.ch 上通过交互方式查看，但该网站不提供服务可调用的接口。

---

工具

工具	描述	主要用例
seco_search_datasets	搜索 opendata.swiss 上的劳动力市场数据集（每条搜索结果均显示发布方）	发现数据
seco_get_dataset	数据集的完整元数据和下载链接	获取数据
seco_get_unemployment_overview	登记失业人数：全国年度数据，以及 TG/FR/ZG/ZH 的州级数据	劳动力市场概览
seco_get_youth_unemployment	青年失业（15–24 岁）——仅提供 TG（人数）和 ZG（比率）数据	🎓 职业选择咨询
seco_get_job_seekers	登记求职者人数，全国年度序列始于 2000 年	培训需求
seco_get_open_positions	空缺职位——没有全国序列	行业分析
seco_get_unemployment_by_occupation	按 Berufshauptgruppe 划分的数据——没有机器可读的数据源	🎓 职业指导
seco_get_monthly_report_url	生成/验证 PDF 报告 URL	访问来源
seco_list_cantons	全部 26 个州的代码和名称	实用工具
seco_get_uvg_overview	关于职业事故和职业病的 UVG 关键数据	风险概览
seco_get_uvg_by_branch	按 NOGA 2008 经济行业划分的结果	🎓 职业指导
seco_get_uvg_trends	按行业划分的十年事故时间序列	趋势分析

12 个工具，最多可提供 15 个。

---

UVG 事故统计（SSUV）

三个 seco_get_uvg_* 工具涵盖了与失业工具所描述的同一劳动力市场中的风险方面：各行业发生了多少起职业事故和职业病，以及这些数据在十年间如何变化。

发布方不是 SECO。 UVG 事故统计由协调小组 KSUV 和位于卢塞恩的 Sammelstelle SSUV c/o Suva 发布。seco_ 前缀指向的是此服务，而非数据来源；每个响应都会在其 source 字段中注明实际发布方。

架构决策：C（优先转储）

已于 2026-08-05 在线验证，完整报告见 PROBE_REPORT_UVG.md。

该数据源没有 API。扫描所有数据页面中的链接后，发现 165 个 PDF，且没有任何 .csv、.xlsx 或 .json 文件。opendata.swiss 完全没有列出该数据源（七个搜索词中有六个的 count=0），而 BFS dam-api 会静默忽略其筛选参数。剩下的内容在实际使用中可供机器读取，但并非专为此设计：

访问方式	格式	更新频率
schluesselzahlen_d.htm	HTML 表格，5 年数据，覆盖全瑞士	每年
Ts{YY}.pdf	年度版本，按 NOGA 划分的表格 1.2 和 2.4	每年 6 月
WirtKl_{BUV|NBUV}_{NN}.pdf	按 NOGA 部门划分的十年序列	每年 1 月

PDF 会缓存 24 小时，并采用 2s/4s/8s 的退避重试。

每个响应都会告诉你什么

• source_freshness.data_year — 数据年份，而非版本年份。2026 年版本报告的是 2024 年数据；这两年的滞后会明确说明，不会隐藏起来。
• totals_check — 对解析出的行进行求和，并与同一出版物中印出的总计进行比较。布局出错会在这里显现，而不会变成看似合理的错误数字。
• significant — 数据源会用星号标记具有统计显著性的同比变化。此标记会保留在每个数据点中，因此只有数据源认定为显著的变化才会被报告为显著。

---

安装

Claude Desktop（stdio）

将以下内容添加到 claude_desktop_config.json：

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

云端 / HTTP

pip install seco-labor-mcp
MCP_TRANSPORT=http PORT=8000 seco-labor-mcp

应使用 http 作为传输方式。只有它能承载现代协议时代：以此服务对象进行测试时，http 会协商使用 2026-07-28，而 sse 会将所有客户端限制在 2025-11-25，即使客户端支持现代协议时代也是如此。现有部署仍可使用 sse 和 streamable-http — tests/test_transport_aera.py 会运行这两种方式，并记录它们实际采用的协议时代。

HTTP 服务默认绑定到 127.0.0.1（环回地址），以防止共享网络上的 NeighborJack。对于确实需要接受容器外部流量的容器部署，请显式设置 HOST=0.0.0.0 — 最好在 Dockerfile / 编排器配置中设置，并且仅在上游代理或防火墙之后使用：

HOST=0.0.0.0 MCP_TRANSPORT=http PORT=8000 seco-labor-mcp   # container only

现在，未知的 MCP_TRANSPORT 值会导致程序报错退出。以前它会静默回退到 stdio，因此拼写错误会让服务启动后始终无法出现在预期端口上。

开发

git clone https://github.com/malkreide/seco-labor-mcp.git
cd seco-labor-mcp
pip install -e ".[dev]"
pytest tests/ -m "not live" -v

---

使用示例

搜索青年失业数据

Tool: seco_search_datasets
Input: { "query": "Jugendarbeitslosigkeit Alter", "limit": 5 }

获取苏黎世州的失业数据

Tool: seco_get_unemployment_overview
Input: { "canton": "ZH", "response_format": "markdown" }

获取月度报告 URL

Tool: seco_get_monthly_report_url
Input: { "year": 2026, "month": 2, "language": "de" }

---

核心概念

失业者（Arbeitslose）与求职者（Stellensuchende）

记忆口诀：失业者 ⊂ 求职者 — 失业者是求职者的子集。

术语	定义	2025 年 12 月
Arbeitslose	在 RAV 登记且可立即工作的人员	~149'000 (3.2%)
Stellensuchende	所有在 RAV 登记的人员（包括参加培训项目者）	~233'900

青年失业的季节性

• 7 月/8 月：大幅增加（毕业后尚未找到工作的学生）
• 9 月/10 月：有所下降（学徒培训开始）
• 秋季下降后仍然存在的剩余失业情况，表明需要采取结构性的过渡项目（Brückenangebote）

职位申报义务（Stellenmeldepflicht，自 2020 年起）

失业率达到或超过 5% 的职业，必须在公开发布职位前向 RAV 申报。名单每年更新。这与职业咨询直接相关 — 这些职业对瑞士求职者而言职位空缺最多。

---

组合协同效应

服务	协同效应
swiss-statistics-mcp	BFS 人口 / 就业数据，可提供更深入的背景信息
zurich-opendata-mcp	苏黎世市级的教育和社会数据
swiss-snb-mcp	经济背景信息（GDP、工资），用于解读劳动力市场
fedlex-mcp	ALV（失业保险）立法框架

---

已知限制

• amstat.arbeit.swiss 没有公共 REST API（JavaScript SPA）→ 可通过 CKAN 作为替代方案
• 职业和行业详情需要从 SECO 资源下载 CSV
• 较早期月度新闻报告的 URL 格式可能有所不同
• 此级别无法获取州级以下的市镇数据
• UVG 数据通过解析 PDF 获取——2025 和 2026 版的版面保持稳定，但重新设计可能导致解析失效。每个响应中的 totals_check 可让这类问题显现，而不是悄无声息地发生。
• UVG 数据大约滞后两年（2026 版报告的是 2024 年数据）
• UVG 分支详情遵循 NOGA 2008，并将部分类别合并（41 – 42、77, 79 – 82）；此级别没有州级细分
• 出版物之外的详细 UVG 数据仅供 SSUV 封闭用户组访问，不在此无认证服务的范围内

第二阶段路线图：

• 自动缓存 CSV，TTL 为 24 小时
• 直接解析 XLSX 以获取州级细分数据
• 与 zh-education-mcp 集成，以关联 Schulamt 专项数据

---

数据许可

适用两种不同的许可——无论哪种情况，此服务的代码均采用 MIT 许可，但数据不受该许可约束。

opendata.swiss 上发布的 SECO / AMSTAT 数据采用知识共享 CCZero（公有领域）许可。 来源：瑞士联邦经济事务秘书处（SECO）——seco.admin.ch

UVG 事故统计数据未采用开放许可。出版物声明：

«Abdruck – ausser für kommerzielle Nutzung – mit Quellenangabe gestattet.» （允许转载，商业用途除外，须注明出处。）

这意味着限制商业用途并要求注明出处。数据归 KSUV/SSUV 所有，不能由此仓库的 MIT 许可解除：MIT 条款适用于代码，而非代码获取的数据。如果你将此服务用于商业用途，UVG 工具不在许可范围内——请直接联系 Sammelstelle ([email protected]) 确认。每个 UVG 响应都会在其 source 字段中重复说明此限制，因为模型不会收到 README。

---

安全与限制

方面	详情
访问权限	只读（readOnlyHint: true）——服务无法修改或删除任何数据
个人数据	不含个人数据——所有来源均为汇总后的匿名公共统计数据
速率限制	没有强制执行的外部限制；服务默认将查询结果限制为 20 条；HTTP 超时为 30 秒
身份验证	无需 API 密钥——opendata.swiss 和 arbeit.swiss 均可公开访问
许可证	SECO 数据采用知识共享 CCZero（公有领域）许可
服务条款	须遵守以下服务条款：opendata.swiss、SECO、arbeit.swiss
GDPR / DSG	完全合规——不会传输或存储个人数据；所有数据均为官方公共统计数据

---

MCP 协议版本

此服务基于 fastmcp 4.x / mcp 2.x，在同一个服务对象上支持两个协议时代：

时代	修订版	形式
现代	2026-07-28	无需握手 — server/discover，每个请求使用一个自包含信封
握手	2025-11-25	先执行 initialize，然后建立有状态会话

支持现代协议时代的客户端会使用该版本；只支持握手时代的客户端也仍可正常使用。两种版本分别在 tests/test_protokoll_aeren.py 中固定，并且都会进行实测——测试会针对此服务对象协商一个真实连接，而不是比较两个常量。

仅固定 LATEST_PROTOCOL_VERSION 并不足够：在 mcp 2.x 中，该名称是现代时代的别名，因此握手时代的版本上限仍可变动——而目前大多数客户端实际使用的正是这个版本上限。

在 0.4.0 之前，此服务运行的是 fastmcp 3.x，该版本固定使用 mcp 1.x。在该版本中，2025-11-25 是 SDK 所知的最高修订版，因此 2026-07-28 并非仅有部分支持——而是完全不存在。过去用于保障单时代状态的测试，如今用于保障其相反状态：如果降级再次移除了现代时代，该测试就会失败。

注意：读取服务元数据时，现代连接上没有 InitializeResult。请使用与时代无关的 protocol_version / server_info，而非 initialize_result。

---

贡献

开发指南请参阅 CONTRIBUTING.md。

---

安全

有关安全措施以及如何报告漏洞，请参阅 SECURITY.md。

---

许可证

基于 MIT License 发布 — 版权所有 © 2026 Hayal Oezkan。

---

作者

Hayal Oezkan · github.com/malkreide

安装

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

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