BISTA MCP — Estatísticas Educacionais de Zurique
malkreide/zh-education-mcp
Acesse dados educacionais de Zurique direto em seus fluxos de IA
Ver no GitHubServidor MCP que conecta assistentes de IA às estatísticas educacionais oficiais do Cantão de Zurique (BISTA). Fornece dados estruturados sobre números de alunos, tendências de distritos escolares, perfis de escolas secundárias, distribuição de nacionalidades e taxas de maturidade. Sem autenticação necessária, dados atualizados anualmente.
Instalação
npx convez-ai malkreide/zh-education-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise de tendências de matrícula por distrito escolar ao longo de anos
- Consultas sobre composição demográfica e nacionalidades em comunidades escolares
- Levantamento de taxas de maturidade e aprovação em ginásios por município
- Pesquisa educacional e planejamento de políticas públicas em educação
Veredito

Ferramenta especializada e bem executada para acesso a dados públicos educacionais suíços. Adequada para pesquisadores, analistas de políticas e assistentes que precisam contexto educacional de Zurique, mas com escopo geográfico restrito.
README
A tradução para o português deste README ainda está na fila.
🇨🇭 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?"
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):
- 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.ai - 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
│ ├── 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_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 (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"
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
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"
]
}
}
}