seco-labor-mcp

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

# SECO Labor Market MCP Server

![Version](https://img.shields.io/badge/version-0.5.0-blue)
[![CI](https://github.com/malkreide/seco-labor-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/malkreide/seco-labor-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/seco-labor-mcp)](https://pypi.org/project/seco-labor-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![No Auth Required](https://img.shields.io/badge/auth-none%20required-brightgreen)](https://github.com/malkreide/seco-labor-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

🌐 **English** | **[Deutsch](README.de.md)**

An MCP (Model Context Protocol) server for Swiss labor market data from **SECO** (Staatssekretariat für Wirtschaft) and **AMSTAT** via opendata.swiss.

<p align="center">
  <img src="assets/demo.png" alt="Demo: Claude queries youth unemployment via seco-labor-mcp tool call" width="720">
</p>

---

## Overview

This server connects AI models to Swiss labor market statistics — unemployment rates, job seekers, open positions, youth unemployment, and occupational breakdowns — all without requiring an API key.

**Primary audiences:**
- 🏫 **Schulamt / Education planning** — youth unemployment, vocational guidance data
- 📊 **Research & analysis** — labor market trends, cantonal comparisons
- 🤖 **AI agents** — automated labor market monitoring and reporting

**Anchor query:**  
*"Welche Berufsgruppen haben im Kanton Zürich die höchste Jugendarbeitslosigkeit, und welche Lehrberufe unterliegen der Stellenmeldepflicht?"*
[→ More use cases by audience →](EXAMPLES.md)

---

## Data Sources (Phase 1 — No Auth Required)

| Source | Description | Status |
|--------|-------------|--------|
| [opendata.swiss](https://opendata.swiss/de/dataset) | CKAN catalogue; the pinned BFS table `T3.3.0.1` carries the SECO annual series | ✅ Live |
| [arbeit.swiss](https://www.arbeit.swiss) | Monthly press reports (PDF, structured URL pattern) | ✅ Live |
| [amstat.ch](https://www.amstat.ch) | AMSTAT reference portal | ⚠️ JavaScript SPA, no public REST API |
| [unfallstatistik.ch](https://www.unfallstatistik.ch) | Unfallstatistik UVG (SSUV/KSUV c/o Suva) — occupational accidents and diseases | ⚠️ PDF only, no API (see below) |

---

## Architecture

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

---

## Where the figures come from — and what is missing

**SECO is no longer a publisher on opendata.swiss.** Verified 2026-08-14:
`organization_show` returns 404, and none of the 176 entries in
`organization_list` is SECO. Until then the server filtered every search on
that organisation and therefore returned **nothing** — a name lookup that
misses looks exactly like an empty search.

The registered unemployed and job seekers are still SECO's figures: the **BFS
publishes them** in table `T3.3.0.1` and names SECO in the footer. The server
reads that table through a **pinned dataset id** (`sources.py`), checked
against the live source by a live test.

| Series | 2000 | 2025 |
|---|---|---|
| Registered job seekers (SECO) | 124.6 | 214.1 |
| Registered unemployed (SECO) | 72.0 | 133.7 |
| ILO unemployed (BFS) | 126.5 | 248.5 |

*thousands, annual average*

The three series do **not** measure the same thing: in 2000 the ILO figure is
1.76× the registered one. The server reports them separately and labelled, and
never converts one into the other.

### The cantonal layer: four cantons, four schemas

There is no national monthly series — but **four cantons publish their own
RAV figures**, each in its own portal with its own column names. For those,
`seco_get_unemployment_overview(canton=…)` returns real values:

| Canton | Granularity | from | Level | Note |
|---|---|---|---|---|
| **TG** | monthly | 2016-01 | canton | only series **by age class** → youth unemployment as a count |
| **FR** | monthly | 2004-01 | canton **and Switzerland** | carries the national monthly figure as a comparison row |
| **ZG** | monthly | 1993-01 | canton | youth unemployment only as a **rate**, not a count |
| **ZH** | **annual** | 1991 | **municipality** | no monthly values; districts and regions sit in the same column as municipalities and are separated out |

**The other 22 cantons get a named refusal** — no figure from another canton
and no national aggregate. Partial coverage that feels complete is worse than
none.

The four series are **not comparable with each other** and do not add up to a
Swiss figure: different time axes, different geographic levels, and in ZG's
case a rate rather than a count.

**Still not available:** unemployment by occupational group, open positions as
a national series, and youth unemployment for Switzerland or for 24 of the 26
cantons. The affected tools say so and return **no** substitute figure. These
values exist interactively on [amstat.ch](https://www.amstat.ch/v2/amstat_de.html),
which offers no interface a server could call.

---

## Tools

| Tool | Description | Key Use Case |
|------|-------------|--------------|
| `seco_search_datasets` | Search labour-market datasets on opendata.swiss (publisher shown per hit) | Discovery |
| `seco_get_dataset` | Full metadata + download links for a dataset | Data access |
| `seco_get_unemployment_overview` | Registered unemployed: national annual, cantonal for TG/FR/ZG/ZH | Labor market overview |
| `seco_get_youth_unemployment` | Youth unemployment (15–24) — **TG** (count) and **ZG** (rate) only | 🎓 Berufswahlberatung |
| `seco_get_job_seekers` | Registered job seekers, national, annual series from 2000 | Training demand |
| `seco_get_open_positions` | Open positions — **no national series available** | Sector analysis |
| `seco_get_unemployment_by_occupation` | Breakdown by Berufshauptgruppe — **no machine-readable source** | 🎓 Vocational guidance |
| `seco_get_monthly_report_url` | Generate/verify PDF report URL | Source access |
| `seco_list_cantons` | All 26 canton codes and names | Utility |
| `seco_get_uvg_overview` | UVG key figures on occupational accidents and diseases | Risk overview |
| `seco_get_uvg_by_branch` | Results per NOGA 2008 economic branch | 🎓 Vocational guidance |
| `seco_get_uvg_trends` | Ten-year accident time series per branch | Trend analysis |

12 of a maximum of 15 tools.

---

## Unfallstatistik UVG (SSUV)

The three `seco_get_uvg_*` tools cover the risk side of the same labour market
the unemployment tools describe: how many occupational accidents and diseases
occur per branch, and how that develops over ten years.

**The publisher is not SECO.** The Unfallstatistik UVG is issued by the
Koordinationsgruppe KSUV and the Sammelstelle SSUV c/o Suva, Lucerne. The
`seco_` prefix addresses this server, not the source; every response names the
actual publisher in its `source` field.

### Architecture decision: C (dump-first)

Verified live on 2026-08-05, full write-up in
[`PROBE_REPORT_UVG.md`](PROBE_REPORT_UVG.md).

The source has **no API**. A link scan across every data page returned 165 PDFs
and zero files with `.csv`, `.xlsx` or `.json`. opendata.swiss does not list the
source at all (`count=0` for six of seven search terms), and the BFS dam-api
silently ignores its filter parameters. What remains is machine-readable in
practice but not by design:

| Access | Format | Refresh |
|---|---|---|
| `schluesselzahlen_d.htm` | HTML table, 5 years, Switzerland-wide | annually |
| `Ts{YY}.pdf` | annual edition, tables 1.2 and 2.4 by NOGA | annually, June |
| `WirtKl_{BUV\|NBUV}_{NN}.pdf` | ten-year series per NOGA division | annually, January |

PDFs are cached for 24 h and fetched with 2s/4s/8s backoff.

### What every response tells you

- `source_freshness.data_year` — the **data** year, not the edition year. The
  2026 edition reports 2024; that two-year lag is stated, not buried.
- `totals_check` — parsed rows are summed and compared against the total
  printed in the same publication. A broken layout shows up here instead of
  becoming a plausible wrong number.
- `significant` — the source marks statistically significant year-on-year
  changes with an asterisk. That flag is preserved per data point, so a change
  is only reported as significant where the source says so.

---

## Installation

### Claude Desktop (stdio)

Add to `claude_desktop_config.json`:

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