Zh Education MCP Server

🇨🇭 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.

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

Example Use Cases

---

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

---

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
│   ├── 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

---

Testing

# Unit tests (no API calls)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (live API calls)
pytest tests/ -m "live"

---

MCP Protocol Version

This server targets the MCP specification as implemented by the pinned mcp[cli] SDK (see pyproject.toml). Protocol/spec-version bumps are recorded in CHANGELOG.md. Dependencies (incl. the MCP SDK) receive monthly update PRs via Dependabot (.github/dependabot.yml).

Project phase: Phase 1 — read-only (all tools readOnlyHint: true). See docs/roadmap.md.

---

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