{
  "markdown": "> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**\n\n# 🎓 global-education-mcp\n\n![Version](https://img.shields.io/badge/version-0.3.5-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)\n[![Data: UNESCO UIS](https://img.shields.io/badge/Data-UNESCO%20UIS-blue)](https://uis.unesco.org/)\n[![Data: OECD](https://img.shields.io/badge/Data-OECD%20EaG-green)](https://www.oecd.org/education/education-at-a-glance/)\n[![Tests](https://img.shields.io/badge/tests-169-brightgreen)](tests/)\n[![No API Key](https://img.shields.io/badge/API%20Key-not%20required-success)](https://uis.unesco.org/bdds)\n![CI](https://github.com/malkreide/global-education-mcp/actions/workflows/ci.yml/badge.svg)\n\n> MCP server for international education data – UNESCO UIS (4,000+ indicators across all member countries) and OECD Education at a Glance via SDMX. No API keys required.\n\n[🇩🇪 Deutsche Version](README.de.md)\n\n![global-education-mcp demo flow](assets/demo-flow.svg)\n\n---\n\n## Overview\n\n**global-education-mcp** gives AI assistants like Claude a complete international education intelligence system – literacy rates, enrolment ratios, education expenditure, teacher salaries, gender parity and SDG-4 monitoring, all accessible through a single standardised MCP interface.\n\nThe server bridges two of the most authoritative sources for internationally comparable education statistics: UNESCO UIS (global coverage, 4,000+ indicators) and the OECD's annual *Education at a Glance* (38 OECD countries, SDMX REST API). Both are open and require no API key.\n\n**Anchor demo query:** *\"Compare Switzerland's education expenditure as a percentage of GDP with Finland, Singapore and South Korea over the last 10 years – and flag any SDG-4 gaps.\"*\n\n---\n\n## Features\n\n- 🌍 **UNESCO UIS** – 4,000+ indicators, all UNESCO member countries, no API key\n- 📊 **OECD Education at a Glance** – 38 OECD countries + partners via SDMX REST\n- 🔍 **Indicator search** – browse and filter the full UNESCO indicator catalogue\n- 🗺️ **Multi-country comparison** – benchmark any indicator across multiple countries\n- 🏫 **Country education profiles** – 10 core indicators in one call\n- 🎯 **SDG-4 monitoring** – structured reporting on Education for All targets\n- 📈 **OECD dataset search** – discover and retrieve Education at a Glance dataflows\n- 🔑 **No API keys required** – fully open data, zero setup friction\n- ☁️ **Dual transport** – stdio for Claude Desktop, Streamable HTTP/SSE for cloud deployment\n- 🛡️ **Graceful degradation** – API failures return helpful messages with local reference fallback\n\n---\n\n## Prerequisites\n\n- Python 3.11+\n- `uv` (recommended) or `pip`\n- No API keys needed\n\n---\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/malkreide/global-education-mcp.git\ncd global-education-mcp\n\n# Install\npip install -e \".[dev]\"\n```\n\nOr with `uvx` (no permanent installation):\n\n```bash\nuvx global-education-mcp\n```\n\n---\n\n## Quickstart\n\n```bash\n# Start the server (stdio mode for Claude Desktop)\nglobal-education-mcp\n```\n\nTry it immediately in Claude Desktop:\n\n> *\"What is Switzerland's literacy rate compared to Finland and Singapore?\"*\n> *\"Show me education expenditure as % of GDP for CHE, DEU and AUT over the last 10 years.\"*\n\n---\n\n## Configuration\n\n### Claude Desktop Configuration\n\n**Windows** (`%APPDATA%\\Claude\\claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"global-education\": {\n      \"command\": \"uvx\",\n      \"args\": [\"global-education-mcp\"]\n    }\n  }\n}\n```\n\n**macOS** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"global-education\": {\n      \"command\": \"uvx\",\n      \"args\": [\"global-education-mcp\"]\n    }\n  }\n}\n```\n\nA ready-to-use `claude_desktop_config.json` is included in the repository root.\n\n### Cloud Deployment (SSE for browser access)\n\nFor use via **claude.ai in the browser** (e.g. on managed workstations without local software).\n\n> ⚠️ **Security note:** Since v0.3, `MCP_HOST` defaults to `127.0.0.1`. The\n> SSE transport must **always** run behind a reverse proxy that adds TLS,\n> authentication, and rate-limiting. Never expose the raw port to the\n> internet — `MCP_HOST=0.0.0.0` is only safe inside an isolated\n> container network.\n\n**Docker (recommended):**\n\nThe repository ships a hardened multi-stage `Dockerfile` and a\n`docker-compose.yml` that applies `read_only: true`, `cap_drop: [ALL]`,\n`security_opt: [no-new-privileges:true]`, and runs as non-root user\n`uid 10001`. The compose file binds the port to `127.0.0.1` so a host-level\nreverse proxy is required for any external access.\n\n```bash\ndocker compose up --build\n# then point nginx/caddy at 127.0.0.1:8000/sse with TLS + auth\n```\n\nPlain `docker run` (without compose):\n\n```bash\ndocker build -t global-education-mcp .\ndocker run --rm \\\n  --read-only --cap-drop ALL --security-opt no-new-privileges \\\n  --tmpfs /tmp:size=16M,mode=1777 \\\n  -p 127.0.0.1:8000:8000 \\\n  global-education-mcp\n```\n\n**Render.com:**\n1. Push/fork the repository to GitHub\n2. On [render.com](https://render.com): New Web Service → connect GitHub repo\n3. Set environment variables in the Render dashboard:\n   ```\n   MCP_TRANSPORT=sse\n   MCP_HOST=0.0.0.0      # Render needs 0.0.0.0; their edge layer provides TLS + auth.\n   PORT=8000\n   ```\n4. In claude.ai under Settings → MCP Servers, add: `https://your-app.onrender.com/sse`\n\n> 💡 *\"stdio for the developer laptop, sandboxed SSE container for the browser.\"*\n\n---\n\n## Available Tools\n\n### UNESCO UIS Tools\n\n| Tool | Description |\n|---|---|\n| `uis_list_indicators` | Search and list available indicators (4,000+) |\n| `uis_list_countries` | List countries and regions with ISO codes |\n| `uis_get_education_data` | Retrieve data for a specific indicator |\n| `uis_compare_countries` | Multi-country comparison for one indicator |\n| `uis_country_education_profile` | Full education profile (10 core indicators) |\n| `uis_list_versions` | List available database versions |\n\n### OECD Tools\n\n| Tool | Description |\n|---|---|\n| `oecd_list_education_datasets` | List Education at a Glance datasets |\n| `oecd_get_education_indicator` | Retrieve OECD education data via SDMX |\n| `oecd_search_datasets` | Search OECD dataflows by keyword |\n\n### Cross-Source Tools\n\n| Tool | Description |\n|---|---|\n| `education_benchmark_countries` | Benchmark multiple countries across 5 focus themes (UNESCO UIS) |\n\n### Resources & Prompts\n\n**Resources:**\n- `education://indicators/unesco` – Quick reference for core UNESCO indicators\n- `education://datasets/oecd` – Quick reference for OECD Education at a Glance dataflows\n\n**Prompts:**\n- `bildungsvergleich_schweiz` – Switzerland vs. Finland, Singapore, Japan\n- `sdg4_monitoring` – SDG-4 report for CH/DE/AT\n\n### Country Codes\n\nISO 3166-1 Alpha-3 standard:\n\n| Code | Country | Code | Country |\n|---|---|---|---|\n| `CHE` | Switzerland | `FIN` | Finland |\n| `DEU` | Germany | `SGP` | Singapore |\n| `AUT` | Austria | `KOR` | South Korea |\n| `FRA` | France | `JPN` | Japan |\n| `SWE` | Sweden | `USA` | United States |\n\n### Example Use Cases\n\n| Query | Tool |\n|---|---|\n| *\"What is Switzerland's literacy rate vs. Finland and Singapore?\"* | `uis_compare_countries` |\n| *\"Education expenditure as % of GDP for CHE, DEU, AUT over 10 years\"* | `uis_get_education_data` |\n| *\"Create a full education profile for South Korea\"* | `uis_country_education_profile` |\n| *\"Which OECD datasets cover teacher salaries?\"* | `oecd_search_datasets` |\n| *\"Compare secondary graduation rates across 5 European countries\"* | `education_benchmark_countries` |\n| *\"Create an SDG-4 monitoring report for Switzerland\"* | `sdg4_monitoring` (prompt) |\n\n→ [More use cases by audience](EXAMPLES.md) →\n\n---\n\n## Architecture\n\n```\n┌─────────────────┐     ┌──────────────────────────────┐     ┌────────────────────┐\n│   Claude / AI   │────▶│   Global Education MCP       │────▶│   UNESCO UIS API   │\n│   (MCP Host)    │◀────│   (MCP Server)               │◀────│   uis.unesco.org   │\n└─────────────────┘     │                              │     └────────────────────┘\n                        │  10 Tools · 2 Resources      │\n                        │   · 2 Prompts                │     ┌────────────────────┐\n                        │  Stdio | SSE                 │────▶│   OECD SDMX API    │\n                        │                              │◀────│   sdmx.oecd.org    │\n                        │  server.py                   │     └────────────────────┘\n                        │   + api_client.py            │\n                        └──────────────────────────────┘\n```\n\n### Infrastructure Components\n\n| Component | Metaphor | Function |\n|---|---|---|\n| HTTPClient | Postal service | Handles all outbound HTTP requests, retries and timeouts |\n| SimpleCache | Whiteboard | In-memory TTL cache for repeated queries |\n| GracefulFallback | Safety net | Returns local reference data when APIs are unavailable |\n| SDMXParser | Translator | Converts OECD SDMX/XML responses to clean JSON |\n\n### Caching Strategy\n\n| Data Source | Cache TTL | Rationale |\n|---|---|---|\n| UNESCO UIS indicators | 3600s | Catalogue is stable; updated annually |\n| UNESCO UIS country data | 1800s | Figures update yearly, not intraday |\n| OECD dataset list | 3600s | Education at a Glance is an annual publication |\n| OECD indicator data | 1800s | Same annual update cycle |\n| Country/region list | 86400s | ISO codes and country lists are highly stable |\n\n---\n\n## Project Structure\n\n```\nglobal-education-mcp/\n├── src/global_education_mcp/       # Main package\n│   ├── __init__.py                 # Package metadata, version\n│   ├── server.py                   # FastMCP server, 10 tools, 2 resources, 2 prompts\n│   └── api_client.py               # HTTP client, UNESCO UIS + OECD wrappers, formatters\n├── scripts/\n│   └── record_fixtures.py          # Records the fixtures from the live UIS API\n├── tests/\n│   ├── fixtures/                   # Recorded responses + PROVENANCE.md (source, date, SHA-256)\n│   ├── fixture_data.py             # Fixture loader – raises on a missing name\n│   ├── test_source_contract.py     # Contract vs. the recording + live tests\n│   ├── test_server.py              # 42 tests (basic / intermediate / advanced)\n│   └── test_extended_scenarios.py  # 74 tests across 8 categories\n├── claude_desktop_config.json      # Ready-to-use Claude Desktop config\n├── pyproject.toml                  # Build configuration (hatchling)\n├── CHANGELOG.md\n├── CONTRIBUTING.md                 # Contribution guide (English)\n├── CONTRIBUTING.de.md              # Contribution guide (German)\n├── SECURITY.md                     # Security policy (English)\n├── SECURITY.de.md                  # Security policy (German)\n├── LICENSE\n├── README.md                       # This file (English)\n└── README.de.md                    # German version\n```\n\n---\n\n## Known Limitations\n\n- **UNESCO UIS:** Some indicators have sparse coverage for low-income countries or recent years\n- **OECD SDMX:** Occasional API timeouts on large multi-country, multi-year requests; reduce the year range if needed\n- **OECD coverage:** 38 OECD members + select partners – does not cover all UNESCO member states\n- **Historical depth:** UNESCO UIS data availability varies by indicator; not all series go back to 1970\n- **Language:** UNESCO UIS returns indicator labels in English only; OECD labels may vary by dataflow\n- **No real-time data:** Both sources publish annually – figures reflect the latest published edition, not live school statistics\n- **Estimated values are labelled:** UIS marks part of its observations `UIS_EST` (UIS estimate) or `NAT_EST` (national estimate) – for `LR.AG15T99` that is 1,306 of 9,818 values. The status column names it; an unlabelled value is a reported one.\n- **Data rows carry the ISO code, not the country name:** plain names come from `uis_list_countries`. The data tools print the code rather than inventing a name.\n- **An unknown country code is not an error status:** UIS answers HTTP 200 with an empty result set and states the reason in the payload's `hints` field. The tools print that hint – otherwise a typo would look exactly like a country without data.\n\n---\n\n## Compliance & Data Classification (City of Zurich)\n\n> Verbindliche Klassifikation für den Einsatz im Schulamt der Stadt Zürich\n> (German section follows in `README.de.md`).\n\n### ISDS Protection Class (Stadt Zürich Schutzbedarfsklassen)\n\n| Dimension | Class | Reasoning |\n|---|---|---|\n| Confidentiality | public | UNESCO UIS data licensed under [CC BY-SA 3.0 IGO](https://creativecommons.org/licenses/by-sa/3.0/igo/); OECD EaG under public [OECD Terms](https://www.oecd.org/termsandconditions/) |\n| Integrity | normal | Upstream is authoritative; local in-memory cache is TTL-bounded and never written to disk |\n| Availability | normal | Graceful fallback to bundled static reference data when an API is unreachable |\n| **Overall protection class** | **G1 — public (öffentlich)** | lowest tier per ISDS Stadt Zürich |\n\n- Data owner: UNESCO UIS / OECD (external)\n- System owner: Schulamt der Stadt Zürich\n- Processes personal data: **no**\n- DSG / EDÖB relevance: **none** (only anonymized country-level aggregates)\n\n### Schulamt Classification (BUI / Vertraulich / Streng Vertraulich)\n\n| Aspect | Classification |\n|---|---|\n| Tool output (Markdown tables, summaries) | **BUI** (betrieblich unkritische Information) |\n| In-memory TTL cache | BUI (same tier as source) |\n| Structured logs (JSON on stderr, see OBS-003) | BUI — only tool name, params, duration; no PII |\n| `tools.lock.json`, `audits/` artefacts | BUI |\n\n→ The server is approved for any Schulamt use case without additional clearance from the data protection officer.\n\n### Compatibility\n\n| Component | Supported version |\n|---|---|\n| MCP Protocol | 2024-11-05 |\n| MCP Python SDK | `>=1.0.0,<2.0.0` |\n| Python | 3.11, 3.12, 3.13 |\n| `httpx` | `>=0.27.0,<1.0.0` |\n| `pydantic` | `>=2.0.0,<3.0.0` |\n\nMajor-version upgrades are deliberate decisions — the upper bounds in\n`pyproject.toml` exist so a transitive bump does not silently break the\nserver. See `CHANGELOG.md` for the upgrade trail.\n\n---\n\n## 🛡️ Safety & Limits\n\n| Aspect | Details |\n|--------|---------|\n| **Access** | Read-only (`readOnlyHint: true`) — the server cannot modify, write or delete any data |\n| **Personal data** | No personal data — UNESCO UIS and OECD EaG publish only aggregated, country-level statistics |\n| **Rate limits** | Built-in per-query caps (max 50 indicators per search, max 10 countries per comparison, conservative year ranges) |\n| **Caching** | In-memory TTL cache (1800–86400s) reduces upstream load and respects publisher capacity |\n| **Timeout** | 30 seconds per upstream API call, with graceful fallback to local reference data |\n| **Authentication** | No API keys required — both UNESCO UIS and OECD SDMX are publicly accessible |\n| **Licenses** | UNESCO UIS data under [CC BY-SA 3.0 IGO](https://creativecommons.org/licenses/by-sa/3.0/igo/); OECD data under [OECD Terms and Conditions](https://www.oecd.org/termsandconditions/) |\n| **Terms of Service** | Subject to ToS of the respective sources: [UNESCO UIS](https://uis.unesco.org/en/terms-and-conditions-use), [OECD](https://www.oecd.org/termsandconditions/) — please cite the source when redistributing |\n| **Attribution** | All tool responses include source attribution (`Source: UNESCO UIS` / `Source: OECD Education at a Glance`) |\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `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. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. This server builds no ASGI app to send an `initialize` through, so\nthe gate asserts the SDK constants rather than a measured response — the\nweaker form, named rather than left unsaid.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n---\n\n## Testing\n\n```bash\n# Unit tests (no API key required, no network)\nPYTHONPATH=src pytest tests/ -v -m \"not integration\"\n\n# Full suite including the live tests against api.uis.unesco.org\nPYTHONPATH=src pytest tests/ -v\n\n# Re-record the fixtures (writes tests/fixtures/ + PROVENANCE.md)\nPYTHONPATH=src python scripts/record_fixtures.py\n```\n\n**169 tests** – 152 offline, 17 against the live source.\n\n| Category | Tests | Description |\n|---|---|---|\n| Edge cases & boundary values | 19 | Year limits, string lengths, null/zero values |\n| Security & adversarial inputs | 14 | Injection attempts, HTTP error codes, whitespace |\n| Output quality | 11 | Markdown structure, source attribution, sort order |\n| Resilience & error cascades | 9 | Full API outage, partial results, timeouts |\n| Subject-matter correctness | 10 | SDG-4 coverage, correct indicators per focus theme |\n| Performance & concurrency | 4 | Concurrent requests, time limits |\n| Schulamt scenarios | 7 | DACH comparison, PISA, teacher shortage |\n| Source contract vs. the recording | 23 | Field names, envelope, query parameters, hints |\n| Live tests (`-m integration`) | 17 | The paths, the shape, and the tools themselves |\n\n### Why the fixtures are recorded rather than written\n\nA hand-written mock encodes its author's assumption and therefore cannot\nrefute it: production code and fixture come from the same head, the same hour,\nthe same reading of the docs. Where both are wrong, both are wrong together —\nand the suite stays green.\n\nThat is not a hypothetical here. Before 2026-08-08 this repo had **128 green\ntests** while three of its four UNESCO paths answered HTTP 404 and every data\nquery returned an empty list. The mocks carried the same invented field names\nas the production code (`observations`, `indicatorId`, `entityType`), so\nnothing could ever contradict them.\n\nEvery fixture under `tests/fixtures/` is now a recorded response.\n`PROVENANCE.md` names the source URL, the recording date, the selection rule\nand the SHA-256 for each one. Without a date, \"recorded\" becomes\nindistinguishable from \"invented\" after two years — the file looks the same.\n\nThree of the fixtures are **controls**: a made-up `theme` value, a made-up\ncountry code, and the same time series requested twice with different\nparameter names. Without them a measurement only shows what *we* received; with\nthem it shows what the source actually distinguishes.\n\n---\n\n## Contributing\n\nContributions are welcome. Please open an issue first to discuss what you would like to change.\n\n- Follow the existing code style (Ruff linting, Black formatting)\n- Add tests for new tools (`tests/test_server.py` or `test_extended_scenarios.py`)\n- Use the `@pytest.mark.integration` marker for tests that call live APIs\n- Update `CHANGELOG.md` and the tool table in this README\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Security\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md) ([🇩🇪 Deutsche Version](SECURITY.de.md)). Please use the private channels described there rather than public issues.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n## Author\n\nHayal Oezkan · [github.com/malkreide](https://github.com/malkreide)\n\n---\n\n## Credits & Related Projects\n\n- **Data:** [UNESCO Institute for Statistics (UIS)](https://uis.unesco.org/) – open education data for all UNESCO member states\n- **Data:** [OECD Education at a Glance](https://www.oecd.org/education/education-at-a-glance/) – annual OECD education statistics via SDMX\n- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) – Anthropic / Linux Foundation\n- **Related:** [swiss-transport-mcp](https://github.com/malkreide/swiss-transport-mcp) – MCP server for Swiss public transport\n- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) – MCP server for Zurich city open data\n- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide)\n\n<!-- mcp-name: io.github.malkreide/global-education-mcp -->\n\n<!-- BEGIN GENERATED: install -->\n## MCP Client Configuration\n\nRun via [`uv`](https://docs.astral.sh/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`):\n\n```json\n{\n  \"mcpServers\": {\n    \"global-education-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"global-education-mcp\"\n      ]\n    }\n  }\n}\n```\n<!-- END GENERATED: install -->\n",
  "bytes": 21728,
  "sha": "d40402bfc0bed0de7e8976972df7226f8ea6042a241331614baa5942e48a2e3e",
  "repo_slug": "malkreide/global-education-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_global_education_mcp_bc5e28b0/readme"
}