openemis

---

title: "openemis-mcp — OpenEMIS 学校管理的 AI 桥梁" description: "免费的只读 MCP 服务，可将 AI 助手连接到 OpenEMIS 学校管理系统。查询学生出勤、风险、教职员工以及 678 项资源。" keywords:

• OpenEMIS
• 学校管理系统
• 教育管理
• 学生出勤
• 学生风险
• MCP 服务

---

openemis-mcp — OpenEMIS 学校管理的 AI 桥梁

连接 AI Agent 与任意 OpenEMIS 学校的免费只读 MCP 桥梁。

OpenEMIS 是由 UNESCO 和 KORDIT 开发的免费开源学校管理信息系统。它负责各类教育机构的日常管理，包括幼儿园、小学、中学、中等职业院校、技术学院和大学，管理学生、教职员工、出勤、评估、基础设施、膳食、奖学金、考试、培训和教育部级别的报告。此 MCP 可让 AI Agent 只读访问任意 OpenEMIS 学校的数据，让你能够用日常英语提问，并在几秒内获得答案。

基于已发布的 OpenEMIS Core API 构建（参考：api.openemis.org/core），并已通过 demo.openemis.org/core 公开演示站点验证。

关于此项目： openemis-mcp 是一款免费的 MCP 服务，可将 AI 助手（Claude、Cursor、Codex）连接到 OpenEMIS 学校管理系统。它通过 26 个精选只读操作手册提供 678 项资源，包括学生、学生出勤、学生风险、教职员工、考试和基础设施；此外，还提供 14 个用于重定向写入操作的存根。

用日常英语提问：

“Avory Primary 目前有多少名在读学生？”

Agent 会规划调用，此 MCP 会提供数据：

“Avory Primary School 目前有 97 名在读学生，分布在 6 个班级。”

无需代码，无需 JSON，直接提问即可。

---

包含内容（免费，MIT）

工具	功能
openemis_health	检查已配置的实例 — 执行真实的登录往返测试
openemis_list_domains	列出 9 个精选领域（出勤、评估、教职员工、学生……）
openemis_discover	主题 → 最多 30 个范围明确的端点，精简对话内容
openemis_list_playbooks	列出全部 40 个操作手册 — 其中 26 个为只读，14 个为重定向到 mcp-pro 的存根
openemis_get_playbook	按 ID 加载操作手册 — 包含完整步骤、资源和注意事项
openemis_get	统一读取：列表或单例，支持任意资源和筛选条件

26 个只读操作手册涵盖出勤、评估、学生档案、教职员工档案、基础设施、膳食、风险仪表板、班级报告、课表、审计日志、学校认证／注册、招生和入学队列状态，以及 OpenEMIS 工作流插件如何驱动每个多步骤审批流程的入门介绍；每个操作手册均已根据 v5 清单验证，资源覆盖率达 100%。另有 14 个操作手册存根可在此处发现，但实际的写入／身份验证步骤需前往 openemis-mcp-pro。

翻译：Русский · Español · हिन्दी · العربية — 最初的 17 个视图操作手册也已翻译成这四种语言；新增的 9 个操作手册（在 v1.1.0 中为 Core 5.10.0 添加，另有两个工作流操作手册）目前仅提供英文版。

✏️ 写入操作（在 OpenEMIS 中创建／更新记录）需要 openemis-mcp-pro。此免费服务有意设置为只读 — 不提供 post、put 和 delete。

Pro 版包含的内容

openemis-mcp-pro 在此免费只读服务的基础上，新增了写入工具、远程托管和 ChatGPT 兼容性。

	免费版	个人 Pro 版	机构 Pro 版	国家 Pro 版
读取工具（全部 678 个资源，Core 5.13.0）	✅	✅	✅	✅
26 个读取工作手册（17 × 5 种语言 + 9 个英文版）	✅	✅	✅	✅
14 个写入 / 身份验证工作手册（mark-attendance、enrol、set-accreditation…）	stub	✅	✅	✅
stdio 模式（Claude Code、Cursor、Cline）	✅	✅	✅	✅
HTTP 服务模式（Oracle / VPS — 安装一次，通过 URL 连接）	—	✅	✅	✅
OpenAPI 适配器（ChatGPT Custom GPT、任何 REST 客户端）	—	✅	✅	✅
直接写入 — 单条记录	—	✅	✅	✅
机构审计追踪	—	—	✅	✅
工作流路由执行	—	—	✅	✅
机构管理员审批关卡	—	—	✅	✅
单个机构内的批量操作	—	—	✅	✅
跨多个机构的批量操作	—	—	—	✅
部委审批关卡	—	—	—	✅
跨机构监督	—	—	—	✅

HTTP 服务模式支持你在 Oracle Always Free ARM 实例上安装一次 Pro，然后从任何设备连接，无需在每台机器上分别设置。内置的 OpenAPI 适配器意味着教师可以使用 ChatGPT（或任何 AI 助手），通过导入单个 schema URL 来标记出勤并查找学生记录。请参阅 ChatGPT Teacher Guide，了解分步设置说明。

→ 定价： [email protected]

---

安装

需要 Node 22+。

git clone https://github.com/tixuz/openemis-mcp.git
cd openemis-mcp
npm install
npm run build
cp .env.example .env
$EDITOR .env

配置

OPENEMIS_BASE_URL=https://demo.openemis.org/core
OPENEMIS_USERNAME=admin
OPENEMIS_PASSWORD=your_password
OPENEMIS_API_KEY=your_api_key

冒烟测试

set -a && source .env && set +a
node scripts/smoke-login.mjs

注册到 Claude Code

claude mcp add openemis \
  --env OPENEMIS_BASE_URL="https://your-instance/core" \
  --env OPENEMIS_USERNAME="…" \
  --env OPENEMIS_PASSWORD="…" \
  --env OPENEMIS_API_KEY="…" \
  -- node "$(pwd)/dist/server.js"

兼容任何支持 MCP 的客户端：Claude Code、Cursor、Cline、Codex（通过 gemmy-and-qwenny），以及任何 stdio MCP 客户端。

详细日志记录（可选）

将每次工具调用及其响应记录为 JSONL — 便于调试、调整工作手册或提交错误报告。

# stderr (visible in your MCP client's log panel)
OPENEMIS_LOG_VERBOSE=1 node dist/server.js

# write to a file
OPENEMIS_LOG_VERBOSE=1 OPENEMIS_LOG_FILE=/tmp/openemis.jsonl node dist/server.js

每行都是一个 JSON 对象：{ts, type:"tool_call"|"tool_result"|"tool_error", tool, args?, result?, latency_ms, ...}。形如凭据的键（password、authorization、api_key、token、secret）会自动脱敏。

⚠️ 隐私： tool_result 条目包含返回给 Agent 的实际 OpenEMIS 数据 — 学生姓名、员工 ID、入学详情。仅在你拥有的实例上启用，或在获得明确同意后启用。默认关闭。

🌐 远程 / 服务端安装： openemis-mcp-pro 新增了 HTTP 服务模式 — 在 Oracle Always Free 上安装一次，所有 AI 助手（Claude Code、Cursor、ChatGPT）即可通过 URL 连接，无需在每台机器上分别设置。请参阅 ChatGPT Teacher Guide，了解如何让教师通过 ChatGPT 标记出勤。

---

工作手册

24 个只读工作流指南 — 请参阅 docs/playbooks/。此处也提供写入类工作手册（标记出勤、为学生办理入学、设置学校认证等）的可发现存根，并指向 openemis-mcp-pro。

读取工作手册（查询学校数据）

#	操作手册	领域	翻译
1	统计空缺职位	教职员工	RU · ES · HI · AR
2	查看学生课表	日程	RU · ES · HI · AR
3	学生仪表板	学生	RU · ES · HI · AR
4	机构概览	机构	RU · ES · HI · AR
5	查看最新考勤情况	考勤	RU · ES · HI · AR
6	查看学生档案	学生	RU · ES · HI · AR
7	查看学生成绩	评估	RU · ES · HI · AR
8	查看班级报告	报告	RU · ES · HI · AR
9	查看课表	日程	RU · ES · HI · AR
10	查看完整机构档案	机构	RU · ES · HI · AR
11	查看完整班级档案	学生	RU · ES · HI · AR
12	查看教职员工的完整档案	教职员工	RU · ES · HI · AR
13	完善学生档案	学生	RU · ES · HI · AR
14	查看机构基础设施	机构	RU · ES · HI · AR
15	查看机构餐食	机构	RU · ES · HI · AR
16	查看学生风险档案和福利个案	学生	RU · ES · HI · AR
17	查看机构风险摘要和警报规则	机构	RU · ES · HI · AR

v1.2.0 新增内容（OpenEMIS Core 5.13.0）

• 通过原生 IN 运算符筛选列表（POCOR-9660）。 _conditions=<field>:IN(1,2,3) 可按值列表筛选任意字段，包括非主键和复合主键资源，因此查询班级名单只需一次调用：先按 institution_class_id 查询 institution-class-students，再使用 _conditions=id:IN(101,102,103) 查询 security-users。现在，params.ids="1,2,3" 默认会合并为一次 ?id=1,2,3 往返请求（仅适用于低于 5.10 的 Core 时，才设置 OPENEMIS_CORE_IN_OPERATOR=off）。
• 更严格的筛选验证（POCOR-9697）。 按资源中不存在的字段筛选时，现在会返回 HTTP 400，而不是静默忽略；请使用资源参考中的确切字段名。
• 新增 3 个只读 Runtime 资源（POCOR-9694）： tasks、task-jobs、task-failures——OpenEMIS Runtime 队列／作业／失败记录的投影。总计 678 个资源 · 3,361 个端点。

v1.1.0 新增内容（OpenEMIS Core 5.10.0）

通过 openemis_get_playbook 加载——完整英文内容位于 data/playbooks.json。翻译和各操作手册的 Markdown 文档将在后续版本中发布。

#	操作手册	领域	功能
18	diagnose-alert-delivery	Alerts	回答“此警报是否真的已发出？”——梳理 POCOR-9509 派发流程。
19	view-school-accreditation	Institution	读取 institution-accreditations 记录（POCOR-9610），推导 Active／Expired／Future 状态。
20	view-school-registration	Institution	读取 institution-registrations 历史记录及 valid_from..valid_to 时间范围。
21	view-institution-budget	Institution	按学期列出 institution-budgets，并解析预算类型。
22	query-student-absence-history	Attendance	通过 institution-student-absences 和 absence-days 汇总缺勤记录。
23	query-user-activity-audit-log	Security	查询 POCOR-9697 的 user_activities 字段级审计跟踪记录。
24	view-class-roster	Institution	依次查询 institution-classes → institution-class-students → 学生详情。
25	view-admission-and-enrolment-queue-state	Workflow	回答“这名未来学生在录取／注册队列中的哪个环节？”——解析 status_id 对应的 workflow_step 名称、当前负责人和完整的状态转换历史。
26	explain-workflow-system	Workflow	解答“为什么这项审批要经过 4 个步骤？”——说明 workflow_models、步骤、状态、状态转换、基于角色的负责人，以及插件如何让各租户配置审批链。

写入／身份验证操作手册（存根——安装 mcp-pro）

mark-student-attendance、mark-staff-attendance、enroll-new-student、record-behavior-incident、submit-exam-marks、generate-student-report-card-pdf、generate-institution-statistics-pdf、add-institution-asset、record-infrastructure-repair、add-meal-programme、resolve-my-identity、set-school-accreditation、set-school-registration、mark-student-meal-participation——均会将 Agent 引导至 openemis-mcp-pro，该项目提供 openemis_create／openemis_update／openemis_delete 和按用户进行的身份验证。

Core 兼容性

已针对 OpenEMIS Core 5.13.0（master，2026 年 6 月）进行测试。也支持 5.7 – 5.12 部署版本——公开 REST 接口向后兼容。

能力标志——POCOR-9660 多 ID GET

openemis_get 支持使用 params.ids = "1,2,3" 批量查询。Core 5.10+ 包含 POCOR-9660（CrudApiController 支持 ?id=1,2,3），因此处理程序默认会将批量查询合并为一次往返请求。若指向缺少原生运算符的旧版 Core（5.7 – 5.9），请强制使用旧版并行扇出：

OPENEMIS_CORE_IN_OPERATOR=off

对于复合主键或视图资源——这些资源不适用 ids——请改用 _conditions=<field>:IN(1,2,3)；它可按值列表筛选任意字段，且不受此标志影响。

架构

Agent (Claude / Cursor / Codex / …)
        │ MCP stdio
openemis-mcp  ←  6 read tools + 26 read playbooks + 14 redirect stubs
        │ HTTPS + Bearer JWT
OpenEMIS Core API  /api/v5/{resource}   (3,361 endpoints across 678 resources)

按领域进行发现可让对话保持简洁——openemis_discover("attendance") 会返回与考勤相关的 20–30 个端点，而不是全部 3,361 个端点。

🖥️ 服务器 / HTTP 模式（在 Oracle 上安装一次，即可从任何地方连接，包括 ChatGPT）可通过 openemis-mcp-pro 使用。

---

文档

• 资源参考 — 全部 678 个资源及其方法可用性（Core 5.13.0）
• 操作手册 — 5 种语言的 17 份视图操作手册 + 9 份较新的、仅提供英文版本的操作手册（后续将提供翻译）
• GLOSSARY.md — 关键术语：OpenEMIS、MCP、考勤、学生风险等
• FAQ.md — 关于使用 OpenEMIS MCP 进行学校管理的常见问题
• ACKNOWLEDGEMENTS.md — 构建此项目的 AI 团队

---

许可证

MIT © 2026 Khindol Madraimov

与 OpenEMIS 或其维护者无关。面向公共 Core API 的第三方桥接工具。凭据保留在你的计算机上。