Global Education Mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio

🎓 global-education-mcp

[Version] [License: MIT] [Python 3.11+] [MCP] [Data: UNESCO UIS] [Data: OECD] [Tests] [No API Key] [CI]

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.

🇩🇪 Deutsche Version

[global-education-mcp demo flow]

Overview

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.

The 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.

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

Features

• 🌍 UNESCO UIS – 4,000+ indicators, all UNESCO member countries, no API key
• 📊 OECD Education at a Glance – 38 OECD countries + partners via SDMX REST
• 🔍 Indicator search – browse and filter the full UNESCO indicator catalogue
• 🗺️ Multi-country comparison – benchmark any indicator across multiple countries
• 🏫 Country education profiles – 10 core indicators in one call
• 🎯 SDG-4 monitoring – structured reporting on Education for All targets
• 📈 OECD dataset search – discover and retrieve Education at a Glance dataflows
• 🔑 No API keys required – fully open data, zero setup friction
• ☁️ Dual transport – stdio for Claude Desktop, Streamable HTTP (/mcp, spec 2026-07-28) for cloud deployment
• 🛡️ Graceful degradation – API failures return helpful messages with local reference fallback

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• No API keys needed

Installation

# Clone the repositorygit clone https://github.com/malkreide/global-education-mcp.gitcd global-education-mcp
# Installpip install -e ".[dev]"

Or with uvx (no permanent installation):

uvx global-education-mcp

Quickstart

# Start the server (stdio mode for Claude Desktop)global-education-mcp

Try it immediately in Claude Desktop:

"What is Switzerland's literacy rate compared to Finland and Singapore?" "Show me education expenditure as % of GDP for CHE, DEU and AUT over the last 10 years."

Configuration

Claude Desktop Configuration

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{  "mcpServers": {    "global-education": {      "command": "uvx",      "args": ["global-education-mcp"]    }  }}

macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{  "mcpServers": {    "global-education": {      "command": "uvx",      "args": ["global-education-mcp"]    }  }}

A ready-to-use claude_desktop_config.json is included in the repository root.

Cloud Deployment (Streamable HTTP for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software).

⚠️ Security note: Since v0.3, MCP_HOST defaults to 127.0.0.1. The HTTP transport must always run behind a reverse proxy that adds TLS, authentication, and rate-limiting. Never expose the raw port to the internet — MCP_HOST=0.0.0.0 is only safe inside an isolated container network.

Docker (recommended):

The repository ships a hardened multi-stage Dockerfile and a docker-compose.yml that applies read_only: true, cap_drop: [ALL], security_opt: [no-new-privileges:true], and runs as non-root user uid 10001. The compose file binds the port to 127.0.0.1 so a host-level reverse proxy is required for any external access.

docker compose up --build# then point nginx/caddy at 127.0.0.1:8000/mcp with TLS + auth

Plain docker run (without compose):

docker build -t global-education-mcp .docker run --rm \  --read-only --cap-drop ALL --security-opt no-new-privileges \  --tmpfs /tmp:size=16M,mode=1777 \  -p 127.0.0.1:8000:8000 \  global-education-mcp

Render.com:

1. Push/fork the repository to GitHub
2. On render.com: New Web Service → connect GitHub repo
3. Set environment variables in the Render dashboard:
   MCP_TRANSPORT=streamable-httpMCP_HOST=0.0.0.0      # Render needs 0.0.0.0; their edge layer provides TLS + auth.PORT=8000

4. In claude.ai under Settings → MCP Servers, add: https://your-app.onrender.com/mcp

Migrating from SSE. Up to v0.3.5 the container defaulted to MCP_TRANSPORT=sse with the endpoint /sse. The default is now streamable-http at /mcp — the transport through which 2026-07-28 clients send their single-POST requests; SSE has been superseded since spec 2025-03-26 and never offered that path. Existing deployments either switch the client URL to /mcp or set MCP_TRANSPORT=sse explicitly; the server then logs a legacy_transport_warning on start. An unknown MCP_TRANSPORT value now aborts the start instead of silently falling back to stdio.

💡 "stdio for the developer laptop, sandboxed Streamable HTTP container for the browser."

Available Tools

UNESCO UIS Tools

OECD Tools

Cross-Source Tools

Resources & Prompts

Resources:

• education://indicators/unesco – Quick reference for core UNESCO indicators
• education://datasets/oecd – Quick reference for OECD Education at a Glance dataflows

Prompts:

• bildungsvergleich_schweiz – Switzerland vs. Finland, Singapore, Japan
• sdg4_monitoring – SDG-4 report for CH/DE/AT

Country Codes

ISO 3166-1 Alpha-3 standard:

Example Use Cases

→ More use cases by audience →

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌────────────────────┐│   Claude / AI   │────▶│   Global Education MCP       │────▶│   UNESCO UIS API   ││   (MCP Host)    │◀────│   (MCP Server)               │◀────│   uis.unesco.org   │└─────────────────┘     │                              │     └────────────────────┘                        │  10 Tools · 2 Resources      │                        │   · 2 Prompts                │     ┌────────────────────┐                        │  stdio | Streamable HTTP     │────▶│   OECD SDMX API    │                        │                              │◀────│   sdmx.oecd.org    │                        │  server.py                   │     └────────────────────┘                        │   + api_client.py            │                        └──────────────────────────────┘

Infrastructure Components

Caching Strategy

Project Structure

global-education-mcp/├── src/global_education_mcp/       # Main package│   ├── __init__.py                 # Package metadata, version│   ├── server.py                   # FastMCP server, 10 tools, 2 resources, 2 prompts│   └── api_client.py               # HTTP client, UNESCO UIS + OECD wrappers, formatters├── scripts/│   └── record_fixtures.py          # Records the fixtures from the live UIS API├── tests/│   ├── fixtures/                   # Recorded responses + PROVENANCE.md (source, date, SHA-256)│   ├── fixture_data.py             # Fixture loader – raises on a missing name│   ├── test_source_contract.py     # Contract vs. the recording + live tests│   ├── test_server.py              # 42 tests (basic / intermediate / advanced)│   └── test_extended_scenarios.py  # 74 tests across 8 categories├── claude_desktop_config.json      # Ready-to-use Claude Desktop config├── pyproject.toml                  # Build configuration (hatchling)├── CHANGELOG.md├── CONTRIBUTING.md                 # Contribution guide (English)├── CONTRIBUTING.de.md              # Contribution guide (German)├── SECURITY.md                     # Security policy (English)├── SECURITY.de.md                  # Security policy (German)├── LICENSE├── README.md                       # This file (English)└── README.de.md                    # German version

Known Limitations

• UNESCO UIS: Some indicators have sparse coverage for low-income countries or recent years
• OECD SDMX: Occasional API timeouts on large multi-country, multi-year requests; reduce the year range if needed
• OECD coverage: 38 OECD members + select partners – does not cover all UNESCO member states
• Historical depth: UNESCO UIS data availability varies by indicator; not all series go back to 1970
• Language: UNESCO UIS returns indicator labels in English only; OECD labels may vary by dataflow
• No real-time data: Both sources publish annually – figures reflect the latest published edition, not live school statistics
• 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.
• 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.
• 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.

Compliance & Data Classification (City of Zurich)

Verbindliche Klassifikation für den Einsatz im Schulamt der Stadt Zürich (German section follows in README.de.md).

ISDS Protection Class (Stadt Zürich Schutzbedarfsklassen)

• Data owner: UNESCO UIS / OECD (external)
• System owner: Schulamt der Stadt Zürich
• Processes personal data: no
• DSG / EDÖB relevance: none (only anonymized country-level aggregates)

Schulamt Classification (BUI / Vertraulich / Streng Vertraulich)

→ The server is approved for any Schulamt use case without additional clearance from the data protection officer.

Compatibility

Major-version upgrades are deliberate decisions — the upper bounds in pyproject.toml exist so a transitive bump does not silently break the server. See CHANGELOG.md for the upgrade trail.

🛡️ Safety & Limits

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.

Over HTTP both eras share the endpoint /mcp (MCP_TRANSPORT=streamable-http, stateless): a request with the MCP-Protocol-Version: 2026-07-28 header is served as a self-contained single exchange — no initialize, no Mcp-Session-Id. The legacy SSE transport (MCP_TRANSPORT=sse) offers no such path and reaches the handshake era only.

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. tests/test_streamable_http.py measures them: it builds the HTTP app with the options main() starts, and sends a 2026-07-28 client, an auto client, a legacy initialize and a raw server/discover through it. The CI Docker job sends the same server/discover to the hardened container.

What 2026-07-28 changes for this server. The logging capability is deprecated (SEP-2577) and is not used: announcements before a fan-out travel as progress 0 of n, operational logs go to stderr as JSON. serverInfo, which now rides in _meta on every response, carries the package version. List methods carry freshness hints (ttlMs, cacheScope, SEP-2549).

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.

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.

Testing

# Unit tests (no API key required, no network)PYTHONPATH=src pytest tests/ -v -m "not integration"
# Full suite including the live tests against api.uis.unesco.orgPYTHONPATH=src pytest tests/ -v
# Re-record the fixtures (writes tests/fixtures/ + PROVENANCE.md)PYTHONPATH=src python scripts/record_fixtures.py

169 tests – 152 offline, 17 against the live source.

Why the fixtures are recorded rather than written

A hand-written mock encodes its author's assumption and therefore cannot refute it: production code and fixture come from the same head, the same hour, the same reading of the docs. Where both are wrong, both are wrong together — and the suite stays green.

That is not a hypothetical here. Before 2026-08-08 this repo had 128 green tests while three of its four UNESCO paths answered HTTP 404 and every data query returned an empty list. The mocks carried the same invented field names as the production code (observations, indicatorId, entityType), so nothing could ever contradict them.

Every fixture under tests/fixtures/ is now a recorded response. PROVENANCE.md names the source URL, the recording date, the selection rule and the SHA-256 for each one. Without a date, "recorded" becomes indistinguishable from "invented" after two years — the file looks the same.

Three of the fixtures are controls: a made-up theme value, a made-up country code, and the same time series requested twice with different parameter names. Without them a measurement only shows what we received; with them it shows what the source actually distinguishes.

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

• Follow the existing code style (Ruff linting, Black formatting)
• Add tests for new tools (tests/test_server.py or test_extended_scenarios.py)
• Use the @pytest.mark.integration marker for tests that call live APIs
• Update CHANGELOG.md and the tool table in this README
• See CONTRIBUTING.md for the full contribution guide

Changelog

See CHANGELOG.md

Security

To report a vulnerability, see SECURITY.md (🇩🇪 Deutsche Version). Please use the private channels described there rather than public issues.

License

MIT License — see LICENSE

Author

Hayal Oezkan · github.com/malkreide

Credits & Related Projects

• Data: UNESCO Institute for Statistics (UIS) – open education data for all UNESCO member states
• Data: OECD Education at a Glance – annual OECD education statistics via SDMX
• Protocol: Model Context Protocol – Anthropic / Linux Foundation
• Related: swiss-transport-mcp – MCP server for Swiss public transport
• Related: zurich-opendata-mcp – MCP server for Zurich city open data
• Portfolio: Swiss Public Data MCP Portfolio

MCP Client Configuration

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": {    "global-education-mcp": {      "command": "uvx",      "args": [        "global-education-mcp"      ]    }  }}