io.github.malkreide/zh-education-mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio

📊 zh-education-mcp

MCP server for education statistics of the Canton and City of Zurich (BISTA)

🇩🇪 Deutsche Version

---

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

---

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-mcp

---

Quickstart

# stdio (for Claude Desktop)
python -m zh_education_mcp.server

# Streamable HTTP (port 8000)
python -m zh_education_mcp.server --http --port 8000

Try 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.json
• Windows: %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):

1. Push/fork the repository to GitHub
2. On render.com: New Web Service → runtime Docker (uses the provided Dockerfile)
3. Set env vars: MCP_TRANSPORT=streamable-http, MCP_HOST=0.0.0.0, MCP_PORT=8000, and MCP_CORS_ORIGINS=https://claude.ai
4. In 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
zh_edu_list_schulgemeinden	List all school communities / Schulkreise in Canton Zurich
zh_edu_schulkreis_trend	Pupil trend by Schulkreis (2000–present)
zh_edu_overview	Canton-wide learner overview by school level
zh_edu_sek1_profil	Secondary I profile (Sek A/B/C breakdown)
zh_edu_staatsangehoerigkeiten	Nationality structure of pupils per school community
zh_edu_maturitaetsquote	Gymnasium graduation rates by municipality / district
zh_edu_wohnort_trend	Residence-based learner trend (Bezirk / Gemeinde)
zh_edu_mittelschulen	Secondary school statistics (Gymnasium, FMS, HMS)

Example Use Cases

Query	Tool
"List all Schulkreise in Zurich"	zh_edu_list_schulgemeinden
"Pupil trend in Letzi over 5 years"	zh_edu_schulkreis_trend
"How many Sek A vs Sek B in Winterthur?"	zh_edu_sek1_profil
"Top nationalities in Zürich-Letzi"	zh_edu_staatsangehoerigkeiten
"Maturitätsquote of Stadt Zürich"	zh_edu_maturitaetsquote

---

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 version

---

Known 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_schulgemeinden to 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 (readOnlyHint: true). The server cannot modify, delete, or write any data.
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
initialize handshake	2024-11-05 … 2025-11-25	What today's clients speak. The server answers with the revision asked for, or with the 2025-11-25 ceiling when the request asks for something newer.
Per-request envelope	2026-07-28	A request carrying the 2026-07-28 _meta envelope opens a modern connection.

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 2026-07-28 requires	How this server supplies it
serverInfo stamp on every result (spec #3002)	Name, title, version, description and website — from the package metadata, see identity.py
server/discover ("Servers MUST implement")	Answers with supportedVersions, capabilities and instructions
instructions for the model	Reference date, suppressed small counts, attribution duty, read-only scope — deliberately the things no tool description carries
resultType on every result	Set by the SDK, asserted here against the wire
Envelope and header validation (Mcp-Method, Mcp-Name, Mcp-Protocol-Version)	A contradicting header is rejected with -32020, a missing envelope with -32602
Freshness hints (SEP-2549)	Every cacheable listing method carries ttlMs 300,000 / cacheScope public; resources/read deliberately does not

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 match server.json name
• server.json description at most 100 characters; the Registry answers 422, and only after the PyPI upload has already succeeded
• server.json version equal to pyproject.toml version, 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"
      ]
    }
  }
}