global-education-mcp

🇨🇭 属于 瑞士公共数据 MCP 组合

🎓 global-education-mcp

国际教育数据 MCP 服务——通过 SDMX 提供 UNESCO UIS（涵盖所有成员国的 4,000 多项指标）和 OECD《教育概览》数据。无需 API 密钥。

🇩🇪 德语版

---

概览

global-education-mcp 为 Claude 等 AI 助手提供完整的国际教育情报系统——识字率、入学率、教育支出、教师薪资、性别平等以及 SDG-4 监测，所有数据均可通过单一标准化 MCP 接口访问。

该服务连接了两个最权威的国际可比教育统计数据源：UNESCO UIS（全球覆盖，4,000 多项指标）和 OECD 年度《教育概览》（38 个 OECD 国家，SDMX REST API）。两者均开放且无需 API 密钥。

示例查询： “比较过去 10 年瑞士、芬兰、新加坡和韩国的教育支出占 GDP 的比例，并指出 SDG-4 方面的差距。”

---

功能

• 🌍 UNESCO UIS——4,000 多项指标，覆盖所有 UNESCO 成员国，无需 API 密钥
• 📊 OECD《教育概览》——通过 SDMX REST 提供 38 个 OECD 国家及合作伙伴的数据
• 🔍 指标搜索——浏览和筛选完整的 UNESCO 指标目录
• 🗺️ 多国比较——跨多个国家对任意指标进行基准比较
• 🏫 国家教育概况——一次调用获取 10 项核心指标
• 🎯 SDG-4 监测——针对全民教育目标的结构化报告
• 📈 OECD 数据集搜索——发现并获取《教育概览》数据流
• 🔑 无需 API 密钥——完全开放的数据，零配置门槛
• ☁️ 双传输方式——stdio 用于 Claude Desktop；Streamable HTTP（/mcp，规范 2026-07-28）用于云端部署
• 🛡️ 优雅降级——API 故障时提供实用提示，并回退至本地参考数据

---

前置条件

• Python 3.11+
• uv（推荐）或 pip
• 无需 API 密钥

---

安装

# Clone the repository
git clone https://github.com/malkreide/global-education-mcp.git
cd global-education-mcp

# Install
pip install -e ".[dev]"

或使用 uvx（无需永久安装）：

uvx global-education-mcp

---

快速开始

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

立即在 Claude Desktop 中试用：

“瑞士的识字率与芬兰和新加坡相比如何？” “显示过去 10 年 CHE、DEU 和 AUT 的教育支出占 GDP 的百分比。”

---

配置

Claude Desktop 配置

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"]
    }
  }
}

仓库根目录中包含可直接使用的 claude_desktop_config.json。

云端部署（用于浏览器访问的 Streamable HTTP）

用于通过浏览器中的 claude.ai 使用（例如在未安装本地软件的受管工作站上）。

⚠️ 安全提示：从 v0.3 起，MCP_HOST 默认值为 127.0.0.1。HTTP 传输必须始终置于反向代理后，该代理需提供 TLS、身份验证和速率限制。切勿将原始端口暴露到互联网——MCP_HOST=0.0.0.0 仅在隔离的容器网络内安全。

Docker（推荐）：

此仓库提供了经过加固的多阶段 Dockerfile 和 docker-compose.yml，其中应用了 read_only: true、cap_drop: [ALL]、 security_opt: [no-new-privileges:true]，并以非 root 用户 uid 10001 运行。compose 文件将端口绑定到 127.0.0.1，因此任何外部访问都需要主机级反向代理。

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

直接使用 docker run（不使用 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. 将仓库推送到 GitHub，或在 GitHub 上 fork 仓库
2. 在 render.com 上：New Web Service → 连接 GitHub 仓库
3. 在 Render 控制面板中设置环境变量：

   MCP_TRANSPORT=streamable-http
   MCP_HOST=0.0.0.0      # Render needs 0.0.0.0; their edge layer provides TLS + auth.
   PORT=8000
   

4. 在 claude.ai 的 Settings → MCP Servers 中，添加：https://your-app.onrender.com/mcp

**从 SSE 迁移。**在 v0.3.5 及更早版本中，容器默认使用 MCP_TRANSPORT=sse， 端点为 /sse。现在默认传输方式为 streamable-http，端点为 /mcp—— 2026-07-28 客户端通过此传输方式发送单次 POST 请求；自规范 2025-03-26 起，SSE 已被取代，且从未提供过这一路径。现有部署需将客户端 URL 切换为 /mcp，或显式设置 MCP_TRANSPORT=sse；此时服务会在启动时记录 legacy_transport_warning。现在，如果 MCP_TRANSPORT 的值未知，服务会中止启动，而不会静默回退到 stdio。

💡 “开发者笔记本电脑上用 stdio，浏览器访问则用沙箱化的 Streamable HTTP 容器。”

---

可用工具

UNESCO UIS 工具

工具	描述
uis_list_indicators	搜索并列出可用指标（4,000+）
uis_list_countries	列出带 ISO 代码的国家和地区
uis_get_education_data	获取特定指标的数据
uis_compare_countries	对单项指标进行多国比较
uis_country_education_profile	完整的教育概况（10 项核心指标）
uis_list_versions	列出可用的数据库版本

OECD 工具

工具	描述
oecd_list_education_datasets	列出《教育概览》数据集
oecd_get_education_indicator	通过 SDMX 获取 OECD 教育数据
oecd_search_datasets	按关键字搜索 OECD 数据流

跨来源工具

工具	描述
education_benchmark_countries	对多个国家在 5 个重点主题上的表现进行基准比较（UNESCO UIS）

资源与提示词

资源：

• education://indicators/unesco – UNESCO 核心指标速查
• education://datasets/oecd – OECD《教育概览》数据流速查

提示词：

• bildungsvergleich_schweiz – 瑞士与芬兰、新加坡、日本的比较
• sdg4_monitoring – CH/DE/AT 的 SDG-4 报告

国家代码

ISO 3166-1 Alpha-3 标准：

代码	国家	代码	国家
CHE	瑞士	FIN	芬兰
DEU	德国	SGP	新加坡
AUT	奥地利	KOR	韩国
FRA	法国	JPN	日本
SWE	瑞典	USA	美国

示例用例

查询	工具
“瑞士的识字率与芬兰和新加坡相比如何？”	uis_compare_countries
“CHE、DEU、AUT 过去 10 年的教育支出占 GDP 的百分比”	uis_get_education_data
“为韩国创建一份完整的教育概况”	uis_country_education_profile
“哪些 OECD 数据集涵盖教师薪资？”	oecd_search_datasets
“比较 5 个欧洲国家的中学毕业率”	education_benchmark_countries
“为瑞士创建一份 SDG-4 监测报告”	sdg4_monitoring（提示词）

→ 按受众划分的更多用例 →

---

架构

┌─────────────────┐     ┌──────────────────────────────┐     ┌────────────────────┐
│   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            │
                        └──────────────────────────────┘

基础设施组件

组件	比喻	功能
HTTPClient	邮政服务	处理所有出站 HTTP 请求、重试和超时
SimpleCache	白板	用于重复查询的内存 TTL 缓存
GracefulFallback	安全网	API 不可用时返回本地参考数据
SDMXParser	翻译器	将 OECD SDMX/XML 响应转换为整洁的 JSON

缓存策略

数据源	缓存 TTL	原因
UNESCO UIS 指标	3600s	目录稳定；每年更新
UNESCO UIS 国家数据	1800s	数据每年更新，而非日内更新
OECD 数据集列表	3600s	《Education at a Glance》为年度出版物
OECD 指标数据	1800s	更新周期相同，均为每年更新
国家/地区列表	86400s	ISO 代码和国家列表高度稳定

---

项目结构

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

---

已知限制

• UNESCO UIS： 部分指标在低收入国家或近期年份的数据覆盖稀疏
• OECD SDMX： 大规模多国家、多年份请求偶尔会遇到 API 超时；如有需要，请缩小年份范围
• OECD 覆盖范围： 38 个 OECD 成员国及部分合作伙伴——不涵盖所有 UNESCO 成员国
• 历史数据深度： UNESCO UIS 数据的可用性因指标而异；并非所有序列都可追溯至 1970 年
• 语言： UNESCO UIS 仅以英语返回指标标签；OECD 标签可能因数据流而异
• 无实时数据： 两个来源均按年发布数据——数据反映最新发布版本，而非实时学校统计数据
• 估算值会标注： UIS 将部分观测值标记为 UIS_EST（UIS 估算值）或 NAT_EST（国家估算值）——对于 LR.AG15T99，9,818 个值中有 1,306 个属于此类。状态列会注明这一点；未标注的值为报告值。
• 数据行包含 ISO 代码，而非国家名称： 普通名称来自 uis_list_countries。数据工具会输出代码，而不会臆造名称。
• 未知国家代码不属于错误状态： UIS 会以 HTTP 200 响应空结果集，并在负载的 hints 字段中说明原因。工具会输出该提示——否则，拼写错误看起来就会与缺少数据的国家完全相同。

---

合规与数据分类（苏黎世市）

苏黎世市学校管理局使用时的强制分类 （德语部分见 README.de.md）。

ISDS 保护等级（苏黎世市保护需求等级）

维度	等级	理由
保密性	公开	UNESCO UIS 数据依据 CC BY-SA 3.0 IGO 许可；OECD EaG 依据公开的 OECD 条款 提供
完整性	普通	上游来源具有权威性；本地内存缓存受 TTL 限制，且绝不会写入磁盘
可用性	普通	API 无法访问时，优雅地回退至捆绑的静态参考数据
总体保护等级	G1 — 公开（öffentlich）	按苏黎世市 ISDS 标准属于最低等级

• 数据所有者：UNESCO UIS / OECD（外部）
• 系统所有者：苏黎世市学校管理局
• 处理个人数据：否
• DSG / EDÖB 相关性：无（仅包含匿名的国家级汇总数据）

教育主管部门分类（BUI / 机密 / 严格机密）

方面	分类
工具输出（Markdown 表格、摘要）	BUI（业务非关键级信息）
内存中的 TTL 缓存	BUI（与源数据处于同一等级）
结构化日志（stderr 上的 JSON，参见 OBS-003）	BUI — 仅记录工具名称、参数和耗时；不含个人身份信息
tools.lock.json、audits/ 产物	BUI

→ 该服务已获准用于任何教育主管部门的使用场景，无需另行取得数据保护官的许可。

兼容性

组件	支持的版本
MCP 协议	2024-11-05
MCP Python SDK	>=1.0.0,<2.0.0
Python	3.11、3.12、3.13
httpx	>=0.27.0,<1.0.0
pydantic	>=2.0.0,<3.0.0

主版本升级需经过审慎决策——pyproject.toml 中的上限旨在防止传递依赖升级悄无声息地破坏服务。升级记录请参见 CHANGELOG.md。

---

🛡️ 安全与限制

方面	详情
访问权限	只读（readOnlyHint: true）——该服务无法修改、写入或删除任何数据
个人数据	不含个人数据——UNESCO UIS 和 OECD EaG 仅发布按国家/地区汇总的统计数据
速率限制	内置单次查询上限（每次搜索最多 50 个指标，每次比较最多 10 个国家/地区，年份范围设置较为保守）
缓存	内存中的 TTL 缓存（1800–86400s）可减少上游负载并遵循发布方的承载能力
超时	每次上游 API 调用超时为 30 秒，并可平稳回退到本地参考数据
身份验证	无需 API 密钥——UNESCO UIS 和 OECD SDMX 均可公开访问
许可证	UNESCO UIS 数据采用 CC BY-SA 3.0 IGO；OECD 数据遵循 OECD 条款与条件
服务条款	受相应数据源的服务条款约束：UNESCO UIS、OECD——再分发时请注明来源
署名	所有工具响应均包含来源署名（Source: UNESCO UIS / Source: OECD Education at a Glance）

---

MCP 协议版本

此服务通过同一端点支持两个协议时期。连接上的客户端首次请求决定适用哪个时期；之后若声称属于另一个时期，则会被拒绝。

时期	修订版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的协议。服务器会返回请求中的修订版本；如果请求的是更新版本，则返回上限 2025-11-25。
逐请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会开启现代连接。

通过 HTTP 时，两个时期共用端点 /mcp（MCP_TRANSPORT=streamable-http，无状态）：携带 MCP-Protocol-Version: 2026-07-28 标头的请求会作为独立的单次交换来处理——不需要 initialize，也不需要 Mcp-Session-Id。旧版 SSE 传输（MCP_TRANSPORT=sse）不支持这条路径，只能使用握手时期。

两个修订版本都固定在 tests/test_protocol_version.py 中，并针对已安装的 SDK 进行断言，因此 Dependabot 升级 mcp 时不会在无提示的情况下更改其中任何一个版本。tests/test_streamable_http.py 会对它们进行验证：该测试使用 main() 启动时采用的选项构建 HTTP 应用，并向其发送 2026-07-28 客户端、auto 客户端、旧版 initialize 请求和原始 server/discover 请求。CI Docker 任务会向加固后的容器发送相同的 server/discover 请求。

2026-07-28 对此服务的影响。 日志记录能力已弃用（SEP-2577），因此不会使用：扇出之前的公告会以进度 0 of n 发送，运行日志则以 JSON 格式写入 stderr。现在每个响应的 _meta 都会携带 serverInfo，其中包含软件包版本。列表方法会携带新鲜度提示（ttlMs、cacheScope、SEP-2549）。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时期的别名，而非握手时期的别名——仅依据它固定版本，会让当前客户端实际协商的时期仍有漂移空间。

更新策略。 当检查失败时，不要盲目修改常量：先阅读两个修订版本之间的规范变更日志，确认服务器仍能正常运行，然后一并更新常量、本节、README.de.md 和 CHANGELOG.md。

---

测试

# 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.org
PYTHONPATH=src pytest tests/ -v

# Re-record the fixtures (writes tests/fixtures/ + PROVENANCE.md)
PYTHONPATH=src python scripts/record_fixtures.py

169 项测试 – 152 项离线测试，17 项针对实时数据源。

类别	测试数	说明
边缘情况和边界值	19	年份限制、字符串长度、null/零值
安全性和对抗性输入	14	注入尝试、HTTP 错误代码、空白字符
输出质量	11	Markdown 结构、来源归属、排序
容错能力和错误级联	9	API 完全不可用、部分结果、超时
主题内容准确性	10	SDG-4 覆盖情况、各重点主题对应的正确指标
性能和并发	4	并发请求、时间限制
教育局场景	7	DACH 比较、PISA、教师短缺
与记录相符的来源契约	23	字段名称、信封、查询参数、提示
实时测试（-m integration）	17	路径、结构以及工具本身

为什么要录制 fixture，而不是手写

手写的 mock 体现的是作者的假设，因此无法证伪这个假设：生产代码和 fixture 来自同一个人、同一个小时，也基于对文档的同一种解读。如果两者都错了，它们就会一起出错——测试套件仍会通过。

这并非假设。在 2026-08-08 之前，这个仓库有 128 个通过的测试，但四条 UNESCO 路径中有三条返回 HTTP 404，而且每个数据查询都返回空列表。mock 使用了与生产代码相同的虚构字段名（observations、indicatorId、entityType），因此它们永远无法相互验证。

现在，tests/fixtures/ 下的每个 fixture 都是录制的响应。PROVENANCE.md 记录了每个响应的来源 URL、录制日期、筛选规则和 SHA-256 值。没有日期，两年后“录制的”就会和“编造的”无法区分——文件看起来完全一样。

其中三个 fixture 是对照项：一个虚构的 theme 值、一个虚构的国家代码，以及使用不同参数名称两次请求的同一时间序列。没有它们，测量结果只能说明我们收到了什么；有了它们，才能说明来源实际区分了什么。

---

贡献

欢迎贡献。请先提交 issue，讨论你想要进行的更改。

• 遵循现有代码风格（Ruff linting、Black 格式化）
• 为新工具添加测试（tests/test_server.py 或 test_extended_scenarios.py）
• 对调用实时 API 的测试使用 @pytest.mark.integration 标记
• 更新 CHANGELOG.md 和本 README 中的工具表格
• 完整的贡献指南请参阅 CONTRIBUTING.md

---

更新日志

请参阅 CHANGELOG.md

---

安全

如需报告漏洞，请参阅 SECURITY.md（🇩🇪 德文版）。请使用其中说明的私密渠道，而不要提交公开 issue。

---

许可证

MIT 许可证——请参阅 LICENSE

---

作者

Hayal Oezkan · github.com/malkreide

---

致谢与相关项目

• 数据： UNESCO Institute for Statistics (UIS) – 面向所有 UNESCO 成员国的开放教育数据
• 数据： OECD Education at a Glance – 通过 SDMX 提供的 OECD 年度教育统计数据
• 协议： Model Context Protocol – Anthropic / Linux Foundation
• 相关项目： swiss-transport-mcp – 瑞士公共交通 MCP 服务
• 相关项目： zurich-opendata-mcp – 苏黎世市开放数据 MCP 服务
• 作品集： Swiss Public Data MCP Portfolio

MCP 客户端配置

通过 uv 的 uvx 运行——无需克隆或手动安装。将其添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

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