zh-education-mcp
This MCP server provides read-only access to official education statistics for the Canton of Zurich (BISTA), covering pupil numbers, school community trends, secondary school profiles, nationalities, graduation rates, and more.
List school communities (
zh_edu_list_schulgemeinden) – find all Schulgemeinden/Schulkreise, optionally filtered by name.Pupil trends by school district (
zh_edu_schulkreis_trend) – track learner numbers over 1–30 years for a given Schulkreis.Canton-wide learner overview (
zh_edu_overview) – aggregate counts by school level, type, and gender.Secondary I profiles (
zh_edu_sek1_profil) – breakdown of pupils by requirement type (Sek A/B/C, Mittelschule, special classes).Nationality structure (
zh_edu_staatsangehoerigkeiten) – top nationalities of pupils in a school community, with ISO2 codes and shares.Gymnasium graduation rates (
zh_edu_maturitaetsquote) – Maturitätsquote by municipality, district, or canton.Residence-based trends (
zh_edu_wohnort_trend) – learner counts by place of residence (Bezirk/Gemeinde) across school levels.Mittelschulen statistics (
zh_edu_mittelschulen) – data on Gymnasium, FMS, HMS by type, educational track, gender, and nationality.All tools support markdown or JSON output and use no authentication (public BISTA API).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zh-education-mcp How has the number of pupils in Schulkreis Letzi developed over the last 5 years?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🇨🇭 Part of the Swiss Public Data MCP Portfolio
📊 zh-education-mcp
MCP server for education statistics of the Canton and City of Zurich (BISTA)
Overview
zh-education-mcp connects AI assistants to the Bildungsstatistik Kanton Zürich (BISTA) — the official education statistics of the Canton of Zurich. It provides structured access to pupil numbers, school district trends, secondary school profiles, nationality breakdowns, and gymnasium graduation rates.
Source | Data | API |
BISTA Kanton Zürich | Learner statistics (Volksschule, Mittelschulen, Maturität) | REST/CSV |
All data is fetched from the BISTA public API (bista.zh.ch/basicapi/ogd/) — no API key required. Data is updated annually on 15 September (reference date).
Anchor demo query: "How has the number of pupils in school district Letzi developed over the last 5 years?"
Related MCP server: swisstopo-mcp
Demo
Features
📊 8 tools for education data across all school levels
🔍 School district trends — pupil numbers for all Schulkreise (Letzi, Glattal, Schwamendingen, Oerlikon, Uto, Waidberg, Zürichberg) from 2000 to present
🏫 Secondary school profiles — breakdown by requirement type (Sek A/B/C, Mittelschule, special classes)
🌐 Nationality structure — top nationalities of pupils per school community
🎓 Gymnasium graduation rates — Maturitätsquote by municipality, district, and canton
📈 Canton-wide overview — all learners by school level, type, gender, and nationality
🏠 Residence-based trends — pupil counts by place of residence (Bezirk / Gemeinde)
🏛️ Mittelschulen — Gymnasium, FMS, HMS statistics
🔓 No API key required — all data under CC BY 4.0
☁️ Dual transport — stdio (Claude Desktop) + Streamable HTTP (cloud)
Prerequisites
Python 3.11+
uv (recommended) or pip
Installation
# Clone the repository
git clone https://github.com/malkreide/zh-education-mcp.git
cd zh-education-mcp
# Install
pip install -e .
# or with uv:
uv pip install -e .Or with uvx (no permanent installation):
uvx zh-education-mcpQuickstart
# stdio (for Claude Desktop)
python -m zh_education_mcp.server
# Streamable HTTP (port 8000)
python -m zh_education_mcp.server --http --port 8000Try it immediately in Claude Desktop:
"Wie hat sich die Lernendenzahl im Schulkreis Letzi entwickelt?" "Zeige die Maturitätsquote der Stadt Zürich" "Welche Nationalitäten sind in Adliswil am häufigsten?"
→ More use cases by audience →
Configuration
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"zh-education": {
"command": "python",
"args": ["-m", "zh_education_mcp.server"]
}
}
}Or with uvx:
{
"mcpServers": {
"zh-education": {
"command": "uvx",
"args": ["zh-education-mcp"]
}
}
}Config file locations:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Cloud Deployment (Streamable HTTP for browser access)
For use via claude.ai in the browser (e.g. on managed workstations without local software):
Render.com (recommended):
Push/fork the repository to GitHub
On render.com: New Web Service → runtime Docker (uses the provided
Dockerfile)Set env vars:
MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8000, andMCP_CORS_ORIGINS=https://claude.aiIn claude.ai under Settings → MCP Servers, add:
https://your-app.onrender.com/mcp
💡 "stdio for the developer laptop, Streamable HTTP for the browser."
Health probe: GET /health. Full deployment guide (container, load balancing, CORS,
resource limits): docs/deployment.md.
Available Tools
Tool | Description |
| List all school communities / Schulkreise in Canton Zurich |
| Pupil trend by Schulkreis (2000–present) |
| Canton-wide learner overview by school level |
| Secondary I profile (Sek A/B/C breakdown) |
| Nationality structure of pupils per school community |
| Gymnasium graduation rates by municipality / district |
| Residence-based learner trend (Bezirk / Gemeinde) |
| Secondary school statistics (Gymnasium, FMS, HMS) |
Example Use Cases
Query | Tool |
"List all Schulkreise in Zurich" |
|
"Pupil trend in Letzi over 5 years" |
|
"How many Sek A vs Sek B in Winterthur?" |
|
"Top nationalities in Zürich-Letzi" |
|
"Maturitätsquote of Stadt Zürich" |
|
Architecture
┌─────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────┐
│ Claude / AI │────▶│ zh-education-mcp │────▶│ BISTA Kanton Zürich │
│ (MCP Host) │◀────│ (MCP Server) │◀────│ REST/CSV (Public API) │
└─────────────────┘ │ │ └──────────────────────────┘
│ 8 Tools │
│ Stdio | Streamable HTTP │
│ 24h Cache │
│ No authentication required │
└──────────────────────────────┘Data Source Characteristics
Source | Protocol | Coverage | Auth | Update |
BISTA Kanton ZH | REST/CSV | Learner statistics 2000–present | None | Annual (15 Sep) |
Project Structure
zh-education-mcp/
├── src/zh_education_mcp/
│ ├── __init__.py # Package
│ ├── config.py # ENV settings (MCP_*)
│ ├── constants.py # API base, endpoints, timeouts
│ ├── logging_setup.py # structured stderr logging
│ ├── identity.py # server identity for `_meta` / `server/discover`
│ ├── provenance.py # response envelope, license attribution
│ ├── http_client.py # egress guard, connection pool, lifespan
│ ├── data.py # cache, CSV fetch, filters, error handling
│ ├── models.py # Pydantic input models
│ ├── tools.py # FastMCP instance, 8 tools, 2 resources
│ └── server.py # thin composition layer + entrypoint
├── tests/
│ └── test_server.py # Unit tests (mocked HTTP with respx)
├── docs/ # deployment, security, egress, roadmap, …
├── Dockerfile # multi-stage, non-root, healthcheck
├── docker-compose.yml # resource limits, read-only rootfs
├── .github/workflows/ci.yml # GitHub Actions (Python 3.11/3.12/3.13)
├── .github/dependabot.yml # monthly dependency updates
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md # + CONTRIBUTING.de.md
├── SECURITY.md # + SECURITY.de.md
├── LICENSE
├── README.md # This file (English)
└── README.de.md # German versionKnown Limitations
Annual updates only: BISTA data is updated once per year (reference date: 15 September). The 24h in-memory cache matches this cycle.
CSV-based API: The BISTA API returns CSV data; large datasets may take a moment to parse.
School community names: Names must match exactly (use
zh_edu_list_schulgemeindento find valid names).
Safety & Limits
Topic | Details |
No personal data | BISTA statistics are aggregated — no individual pupil data is exposed or accessible. All figures are anonymized at the school community level. |
Read-only | All tools are read-only ( |
No authentication | The BISTA API is fully public. No API keys, tokens, or credentials are stored or transmitted. |
Rate limits | The BISTA API has no documented rate limit, but the server uses a 24h in-memory cache to minimize requests. Please use responsibly. |
Data license | All data is published under CC BY 4.0 by the Canton of Zurich. Attribution: Bildungsstatistik Kanton Zürich (BISTA). |
Terms of Service | Usage is subject to the BISTA terms of use. The MCP server is an independent open-source project and is not affiliated with the Canton of Zurich. |
AI output disclaimer | Statistics are passed through as-is from the BISTA API. AI-generated interpretations or summaries should be verified against the official BISTA portal. |
Testing
# Unit tests (no API calls)
PYTHONPATH=src pytest tests/ -m "not live"
# Integration tests (live API calls)
pytest tests/ -m "live"The live suite also runs on a schedule: every Monday 05:23 UTC, plus on
demand (live-tests.yml). A red run opens
an upstream-labelled issue; a green one closes it. -m "not live" is not a
place where tests run, and these three are the only tests here that can
contradict a wrong assumption about BISTA — see
CONTRIBUTING.
MCP Protocol Version
This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.
Era | Revision | Who reaches it |
|
| What today's clients speak. The server answers with the revision asked for, or with the |
Per-request envelope |
| A request carrying the |
Both revisions are pinned in
tests/test_protocol_version.py and asserted
against the installed SDK, so a Dependabot bump of mcp cannot move either one
silently. The handshake ceiling is measured against a live initialize through
the assembled ASGI stack, not read off a constant name.
Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern
era, not for the handshake era — pinning against it alone would leave the era
that current clients actually negotiate free to drift.
What the server itself contributes on the modern era
Speaking the revision is the SDK's job. What a server has to supply is listed
here, and measured in
tests/test_modern_protocol.py against real
requests through the assembled ASGI stack rather than against constants:
What | How this server supplies it |
| Name, title, version, description and website — from the package metadata, see |
| Answers with |
| Reference date, suppressed small counts, attribution duty, read-only scope — deliberately the things no tool description carries |
| Set by the SDK, asserted here against the wire |
Envelope and header validation ( | A contradicting header is rejected with |
Freshness hints (SEP-2549) | Every cacheable listing method carries |
The identity is not maintained in src/: version, description and website
come from the distribution metadata and therefore from pyproject.toml — the
one source check_version_sync.py permits.
Before this revision the server stamped version: "" onto every modern-era
result.
Update policy. When the gate fails, do not edit the constant blindly: read
the spec changelog between the two revisions, verify the server still behaves,
then move the constant, this section, README.de.md and
CHANGELOG.md together.
Project phase: Phase 1 — read-only (all tools readOnlyHint: true). See
docs/roadmap.md.
Release
Publishing is driven by a GitHub release (release: published →
publish.yml): build → gate → PyPI → MCP Registry.
The gate (check_release_artifacts.py) runs
before the upload and inspects the built wheel, not the sources:
exactly one
mcp-name:marker (an HTML comment, see the bottom of this file) in the wheel METADATA — the MCP Registry proves PyPI ownership with it — and it must matchserver.jsonnameserver.jsondescriptionat most 100 characters; the Registry answers422, and only after the PyPI upload has already succeededserver.jsonversion equal topyproject.tomlversion, and the git tag equal to the version actually built
It sits ahead of the upload because nothing is correctable behind it: a PyPI version is immutable, so a fix costs a version bump.
If you edit this README: the marker at the very bottom is shipped as part of
the package description (readme = "README.md" in pyproject.toml), and removing
it fails the gate. README.de.md carries no marker and is not published. The
version badge above is checked on every pull request by
check_version_sync.py against pyproject.toml
and server.json.
Changelog
See CHANGELOG.md
Contributing
See CONTRIBUTING.md · 🇩🇪 Beitragen
Security
See SECURITY.md · 🇩🇪 Sicherheit
License
MIT License — see LICENSE
Author
Hayal Oezkan · malkreide
Credits & Related Projects
BISTA: pub.bista.zh.ch — Bildungsstatistik Kanton Zürich (CC BY 4.0)
Protocol: Model Context Protocol — Anthropic / Linux Foundation
Related: zurich-opendata-mcp — Zurich city open data (parking, weather, parliament)
Related: swiss-cultural-heritage-mcp — Swiss cultural heritage data
Related: fedlex-mcp — Swiss federal law
Portfolio: Swiss Public Data MCP Portfolio
Installation
Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):
{
"mcpServers": {
"zh-education-mcp": {
"command": "uvx",
"args": [
"zh-education-mcp"
]
}
}
}Available Tools
8 toolszh_edu_list_schulgemeindenARead-onlyIdempotent
Listet alle Schulgemeinden und Schulkreise im Kanton Zürich auf.
Extrahiert die eindeutigen Schulgemeinden aus den Sekundarstufe-I-Daten. Nützlich als Einstieg, um gültige Namen für andere Tools zu finden.
Args: params (ListSchulgemeindensInput): - suchbegriff (str | None): Filter nach Teilstring (z. B. 'Zürich') - response_format: 'markdown' oder 'json'
Returns: str: Alphabetische Liste aller Schulgemeinden.
Inputs: params (required). Returns: result
zh_edu_maturitaetsquoteARead-onlyIdempotent
Zeigt die gymnasiale Maturitätsquote nach Gemeinde, Bezirk und Kanton.
Die Maturitätsquote berechnet sich als Anteil der gymnasialen Abschlüsse an der 19-jährigen Wohnbevölkerung einer Gemeinde.
Args: params (MaturitaetsquoteInput): - gemeinde (str | None): Gemeindename filtern - bezirk (str | None): Bezirk filtern - response_format: 'markdown' oder 'json'
Returns: str: Maturitätsquoten-Tabelle mit Abschlüssen und Quote pro Gemeinde.
Inputs: params (required). Returns: result
zh_edu_mittelschulenARead-onlyIdempotent
Zeigt Statistiken zu Mittelschulen (Gymnasium, FMS, HMS) im Kanton Zürich.
Umfasst Lernendenzahlen nach Mittelschultyp, Bildungsart, Geschlecht und Staatsangehörigkeit.
Args: params (MittelschulenInput): - mittelschultyp (str | None): Schultyp filtern (z. B. 'Gymnasium') - jahr (int | None): Bestimmtes Jahr (leer = aktuellstes) - response_format: 'markdown' oder 'json'
Returns: str: Mittelschulstatistiken nach Typ und Bildungsart.
Inputs: params (required). Returns: result
zh_edu_overviewARead-onlyIdempotent
Gibt eine kantonsweite Übersicht aller Lernenden nach Stufe, Typ und Geschlecht.
Datenquelle: BISTA-Übersicht aller Lernenden im Kanton Zürich. Umfasst Primarstufe, Sekundarstufe I, Sekundarstufe II und Tertiärstufe.
Args: params (UebersichtInput): - jahr (int | None): Bestimmtes Jahr (leer = aktuellstes) - stufe (str | None): Filter nach Schulstufe - response_format: 'markdown' oder 'json'
Returns: str: Übersichtstabelle mit Lernenden nach Stufe und Schultyp.
Inputs: params (required). Returns: result
zh_edu_schulkreis_trendARead-onlyIdempotent
Zeigt den Lernenden-Trend für eine Schulgemeinde / einen Schulkreis.
Liefert die Entwicklung der Lernendenzahlen (Sek I) über die letzten N Jahre, aufgeschlüsselt nach Anforderungstyp (Sek A, Sek B, Sek C etc.).
Args: params (SchulkreisTrendInput): - schulgemeinde (str): Name der Schulgemeinde (z. B. 'Zürich-Letzi') - letzte_n_jahre (int): Anzahl Jahre rückwärts (Standard: 5) - response_format: 'markdown' oder 'json'
Returns: str: Trend-Übersicht mit Jahresvergleich und Gesamtentwicklung.
Inputs: params (required). Returns: result
zh_edu_sek1_profilARead-onlyIdempotent
Zeigt das Sek-I-Profil einer Schulgemeinde (Anforderungstypen A/B/C).
Schlüsselt die Lernenden der Sekundarstufe I nach Anforderungstyp auf: Sek A (höchste Anforderungen), Sek B, Sek C, Mittelschule, Sonderklassen.
Args: params (Sek1ProfilInput): - schulgemeinde (str): Schulgemeinde (z. B. 'Zürich-Letzi') - jahr (int | None): Bestimmtes Jahr (leer = aktuellstes) - response_format: 'markdown' oder 'json'
Returns: str: Profil mit Anzahl und Anteil pro Anforderungstyp.
Inputs: params (required). Returns: result
zh_edu_staatsangehoerigkeitenARead-onlyIdempotent
Zeigt die Staatsangehörigkeitsstruktur der Lernenden einer Schulgemeinde.
Liefert die häufigsten Nationalitäten der Schüler·innen in einer Schulgemeinde, inkl. ISO2-Ländercode und Anteil.
Args: params (StaatsangehoerigkeitInput): - schulgemeinde (str): Schulgemeinde (z. B. 'Zürich-Letzi') - top_n (int): Anzahl Top-Nationalitäten (Standard: 10) - jahr (int | None): Bestimmtes Jahr (leer = aktuellstes) - response_format: 'markdown' oder 'json'
Returns: str: Rangliste der häufigsten Nationalitäten mit Anteil.
Inputs: params (required). Returns: result
zh_edu_wohnort_trendARead-onlyIdempotent
Zeigt die Entwicklung der Lernendenzahlen nach Wohnort (Bezirk/Gemeinde).
Basiert auf dem Wohnort der Lernenden, nicht dem Schulort. Aufschlüsselung nach Gebietstyp (Kanton, Bezirk, Gemeinde) und Schulstufe.
Args: params (WohnortTrendInput): - gebiet (str | None): Gebietsbezeichnung filtern - stufe (str | None): Schulstufe filtern - letzte_n_jahre (int): Anzahl Jahre (Standard: 5) - response_format: 'markdown' oder 'json'
Returns: str: Trend-Tabelle der Lernenden nach Wohnort und Stufe.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a unique aspect of Zurich education data: listing districts, trends per district, canton-wide overview, Sek1 profiles, nationalities, maturity rates, residence trends, and secondary school statistics. The two trend tools are clearly differentiated by school location vs. residence.
All tools consistently use the zh_edu_ prefix and snake_case, with descriptive names that reflect their purpose (e.g., list_schulgemeinden, maturitaetsquote). The mix of German and English terms is predictable and does not hinder usability.
Eight tools is well within the ideal range for an education statistics server. Each tool covers a distinct facet without redundancy, making the set feel appropriately scoped.
The set covers listing, trends, profiles, demographics, and specific school types comprehensively. Minor gaps exist, such as a lack of tools for raw data export or per-school detailed statistics, but the core analytics needs are well met.
Maintenance
Related MCP Connectors
opendata.swiss MCP — Switzerland's federal open-data portal (CKAN catalogue).
MCP server for Statistics Sweden (SCB) - 1200+ tables with population, economy, environment data
Educational MCP server with 17 math/stats tools, visualizations, and persistent workspace
Related MCP Servers
- AlicenseBqualityBmaintenanceAn MCP server providing AI-powered access to Open Data from the City of Zurich, enabling queries to 900+ datasets, real-time environmental and mobility data, geodata, parliamentary proceedings, and more.2658 PyPI9MIT
- AlicenseAqualityBmaintenanceMCP server for Swiss federal geodata -- maps, elevation, geocoding, cadastral extracts, and downloadable datasets via Swisstopo APIs.2062 PyPI12MIT
- AlicenseAqualityDmaintenanceAn unofficial MCP server for accessing Swiss Federal Statistical Office (BFS) data.81MIT
- AlicenseAqualityAmaintenanceMCP server for Swiss BAKOM open data, enabling natural-language queries about broadband availability, 5G/4G coverage, mobile antennas, licensed broadcasters, and telecom statistics.1273 PyPIMIT