{
  "markdown": "---\ntitle: \"openemis-mcp — AI bridge for OpenEMIS school management\"\ndescription: \"Free, read-only MCP server that connects AI assistants to OpenEMIS school management. Query student attendance, risks, staff, and 678 resources.\"\nkeywords:\n  - OpenEMIS\n  - school management system\n  - education management\n  - student attendance\n  - student risks\n  - MCP server\n---\n\n<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"openemis-mcp logo — AI bridge for OpenEMIS school management\" width=\"320\">\n</p>\n\n# openemis-mcp — AI bridge for OpenEMIS school management\n\n**Free, read-only MCP bridge between AI agents and any OpenEMIS school.**\n\n[**OpenEMIS**](https://www.openemis.org) is a free, open-source **school management information system** developed by UNESCO and KORDIT. It runs the day-to-day administration of every kind of educational institution — kindergartens, primary schools, secondary schools, secondary vocational institutions, technical colleges, and universities — managing students, staff, attendance, assessment, infrastructure, meals, scholarships, examinations, training, and ministry-level reporting. This MCP gives AI agents read-only access to the data in any OpenEMIS school so you can ask questions in plain English and get answers in seconds.\n\nBuilt on the published **OpenEMIS Core API** (reference: [api.openemis.org/core](https://api.openemis.org/core)) and verified against the public demo at [demo.openemis.org/core](https://demo.openemis.org/core).\n\n> **What this is:** openemis-mcp is a free MCP server that connects AI assistants (Claude, Cursor, Codex) to the OpenEMIS school management system. It exposes 678 resources — students, student attendance, student risks, staff, exams, infrastructure — across 26 curated read-only playbooks, plus 14 redirect stubs for write operations.\n\nAsk in plain English:\n\n> *\"How many current students are at Avory Primary?\"*\n\nThe agent plans the calls, this MCP delivers the data:\n\n> *\"Avory Primary School has 97 currently enrolled students across 6 classes.\"*\n\nNo code. No JSON. Just ask.\n\n---\n\n## What's included (free, MIT)\n\n| Tool | What it does |\n|---|---|\n| `openemis_health` | Ping the configured instance — real login round-trip |\n| `openemis_list_domains` | List the 9 curated domains (Attendance, Assessment, Staff, Student…) |\n| `openemis_discover` | Topic → up to 30 scoped endpoints. Keeps conversations small |\n| `openemis_list_playbooks` | List all 40 playbooks — 26 read-only here, 14 stubs that redirect to mcp-pro |\n| `openemis_get_playbook` | Load a playbook by id — full steps, resources, gotcha notes |\n| `openemis_get` | Unified read: list or singleton, any resource, any filter |\n\n**26 read-only playbooks** covering attendance, assessment, student profiles, staff profiles, infrastructure, meals, risk dashboards, class reports, timetables, audit logs, school accreditation / registration, **admission and enrolment queue state**, and a primer on how the OpenEMIS workflow plugin powers every multi-step approval — each verified against the v5 manifest at 100% resource coverage. **14 additional playbook stubs** are discoverable here but redirect to **[openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro)** for the actual write/auth steps.\n\n**Translations:** [Русский](docs/translations/README.ru.md) · [Español](docs/translations/README.es.md) · [हिन्दी](docs/translations/README.hi.md) · [العربية](docs/translations/README.ar.md) — the original 17 view playbooks also translated in all four languages; 9 newer playbooks (added in v1.1.0 for Core 5.10.0, plus the two workflow playbooks) are English-only for now.\n\n> ✏️ **Write operations** (creating/updating records in OpenEMIS) require **[openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro)**. This free server is intentionally read-only — `post`, `put`, and `delete` are not available.\n\n## What's in Pro\n\n`openemis-mcp-pro` adds write tools, remote hosting, and ChatGPT compatibility on top of this free read-only server.\n\n| | **Free** | **Individual Pro** | **Institution Pro** | **Country Pro** |\n|---|---|---|---|---|\n| Read tools (all 678 resources, Core 5.13.0) | ✅ | ✅ | ✅ | ✅ |\n| 26 read playbooks (17 × 5 languages + 9 EN) | ✅ | ✅ | ✅ | ✅ |\n| 14 write / auth playbooks (mark-attendance, enrol, set-accreditation…) | stub | ✅ | ✅ | ✅ |\n| stdio mode (Claude Code, Cursor, Cline) | ✅ | ✅ | ✅ | ✅ |\n| **HTTP server mode** (Oracle / VPS — install once, connect by URL) | — | ✅ | ✅ | ✅ |\n| **OpenAPI adapter** (ChatGPT Custom GPT, any REST client) | — | ✅ | ✅ | ✅ |\n| Direct write — single record | — | ✅ | ✅ | ✅ |\n| Institution audit trail | — | — | ✅ | ✅ |\n| Workflow route execution | — | — | ✅ | ✅ |\n| Institution-admin approval gate | — | — | ✅ | ✅ |\n| Batch ops within one institution | — | — | ✅ | ✅ |\n| Multi-institution batch ops | — | — | — | ✅ |\n| Ministry approval gates | — | — | — | ✅ |\n| Cross-institution oversight | — | — | — | ✅ |\n\n**HTTP server mode** lets you install Pro once on an [Oracle Always Free](https://www.oracle.com/cloud/free/) ARM instance and connect from any device — no per-machine setup. The built-in OpenAPI adapter means teachers can use **ChatGPT** (or any AI assistant) to mark attendance and look up student records by importing a single schema URL. See the [ChatGPT Teacher Guide](https://github.com/tixuz/openemis-mcp-pro/blob/main/docs/CHATGPT-TEACHER-GUIDE.md) for step-by-step setup.\n\n→ **Pricing:** khindol.madraimov@gmail.com\n\n---\n\n## Install\n\nRequires **Node 22+**.\n\n```bash\ngit clone https://github.com/tixuz/openemis-mcp.git\ncd openemis-mcp\nnpm install\nnpm run build\ncp .env.example .env\n$EDITOR .env\n```\n\n### Configure\n\n```env\nOPENEMIS_BASE_URL=https://demo.openemis.org/core\nOPENEMIS_USERNAME=admin\nOPENEMIS_PASSWORD=your_password\nOPENEMIS_API_KEY=your_api_key\n```\n\n### Smoke test\n\n```bash\nset -a && source .env && set +a\nnode scripts/smoke-login.mjs\n```\n\n### Register with Claude Code\n\n```bash\nclaude mcp add openemis \\\n  --env OPENEMIS_BASE_URL=\"https://your-instance/core\" \\\n  --env OPENEMIS_USERNAME=\"…\" \\\n  --env OPENEMIS_PASSWORD=\"…\" \\\n  --env OPENEMIS_API_KEY=\"…\" \\\n  -- node \"$(pwd)/dist/server.js\"\n```\n\nWorks with any MCP-compatible client: Claude Code, Cursor, Cline, Codex (via [gemmy-and-qwenny](https://github.com/tixuz/gemmy-and-qwenny)), or any stdio MCP client.\n\n### Verbose logging (optional)\n\nCapture every tool call and its response as JSONL — useful for debugging, tuning playbooks, or sharing a bug report.\n\n```bash\n# stderr (visible in your MCP client's log panel)\nOPENEMIS_LOG_VERBOSE=1 node dist/server.js\n\n# write to a file\nOPENEMIS_LOG_VERBOSE=1 OPENEMIS_LOG_FILE=/tmp/openemis.jsonl node dist/server.js\n```\n\nEach line is a JSON object: `{ts, type:\"tool_call\"|\"tool_result\"|\"tool_error\", tool, args?, result?, latency_ms, ...}`. Credential-shaped keys (`password`, `authorization`, `api_key`, `token`, `secret`) are redacted automatically.\n\n> ⚠️ **Privacy:** `tool_result` entries contain the actual OpenEMIS data returned to the agent — student names, staff IDs, enrollment details. Enable only on instances you own, or with explicit consent. Default is OFF.\n\n> 🌐 **Remote / server install:** [openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro) adds an HTTP server mode — install once on Oracle Always Free and every AI assistant (Claude Code, Cursor, **ChatGPT**) connects by URL with no per-machine setup. See the [ChatGPT Teacher Guide](https://github.com/tixuz/openemis-mcp-pro/blob/main/docs/CHATGPT-TEACHER-GUIDE.md) for how to let teachers mark attendance via ChatGPT.\n\n---\n\n## Playbooks\n\n24 read-only workflow guides — see [docs/playbooks/](docs/playbooks/). Write-side playbooks (mark attendance, enrol a student, set school accreditation, etc.) are discoverable here as stubs that point at **[openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro)**.\n\n### Read playbooks (school data lookups)\n\n| # | Playbook | Domain | Translations |\n|---|---|---|---|\n| 1 | [Count Vacant Positions](docs/playbooks/count-vacant-positions.md) | Staff | [RU](docs/playbooks/count-vacant-positions.ru.md) · [ES](docs/playbooks/count-vacant-positions.es.md) · [HI](docs/playbooks/count-vacant-positions.hi.md) · [AR](docs/playbooks/count-vacant-positions.ar.md) |\n| 2 | [View Student Timetable](docs/playbooks/view-student-timetable.md) | Schedule | [RU](docs/playbooks/view-student-timetable.ru.md) · [ES](docs/playbooks/view-student-timetable.es.md) · [HI](docs/playbooks/view-student-timetable.hi.md) · [AR](docs/playbooks/view-student-timetable.ar.md) |\n| 3 | [Student Dashboard](docs/playbooks/student-dashboard.md) | Student | [RU](docs/playbooks/student-dashboard.ru.md) · [ES](docs/playbooks/student-dashboard.es.md) · [HI](docs/playbooks/student-dashboard.hi.md) · [AR](docs/playbooks/student-dashboard.ar.md) |\n| 4 | [Institution Summary](docs/playbooks/institution-summary.md) | Institution | [RU](docs/playbooks/institution-summary.ru.md) · [ES](docs/playbooks/institution-summary.es.md) · [HI](docs/playbooks/institution-summary.hi.md) · [AR](docs/playbooks/institution-summary.ar.md) |\n| 5 | [View Latest Attendance](docs/playbooks/view-latest-attendance.md) | Attendance | [RU](docs/playbooks/view-latest-attendance.ru.md) · [ES](docs/playbooks/view-latest-attendance.es.md) · [HI](docs/playbooks/view-latest-attendance.hi.md) · [AR](docs/playbooks/view-latest-attendance.ar.md) |\n| 6 | [View Student Profile](docs/playbooks/view-student-profile.md) | Student | [RU](docs/playbooks/view-student-profile.ru.md) · [ES](docs/playbooks/view-student-profile.es.md) · [HI](docs/playbooks/view-student-profile.hi.md) · [AR](docs/playbooks/view-student-profile.ar.md) |\n| 7 | [View Student Marks](docs/playbooks/view-student-marks.md) | Assessment | [RU](docs/playbooks/view-student-marks.ru.md) · [ES](docs/playbooks/view-student-marks.es.md) · [HI](docs/playbooks/view-student-marks.hi.md) · [AR](docs/playbooks/view-student-marks.ar.md) |\n| 8 | [View Class Report](docs/playbooks/view-class-report.md) | Report | [RU](docs/playbooks/view-class-report.ru.md) · [ES](docs/playbooks/view-class-report.es.md) · [HI](docs/playbooks/view-class-report.hi.md) · [AR](docs/playbooks/view-class-report.ar.md) |\n| 9 | [View Timetable](docs/playbooks/view-timetable.md) | Schedule | [RU](docs/playbooks/view-timetable.ru.md) · [ES](docs/playbooks/view-timetable.es.md) · [HI](docs/playbooks/view-timetable.hi.md) · [AR](docs/playbooks/view-timetable.ar.md) |\n| 10 | [View Full Institution Profile](docs/playbooks/view-institution-profile.md) | Institution | [RU](docs/playbooks/view-institution-profile.ru.md) · [ES](docs/playbooks/view-institution-profile.es.md) · [HI](docs/playbooks/view-institution-profile.hi.md) · [AR](docs/playbooks/view-institution-profile.ar.md) |\n| 11 | [View Full Class Profile](docs/playbooks/view-class-profile.md) | Student | [RU](docs/playbooks/view-class-profile.ru.md) · [ES](docs/playbooks/view-class-profile.es.md) · [HI](docs/playbooks/view-class-profile.hi.md) · [AR](docs/playbooks/view-class-profile.ar.md) |\n| 12 | [View a Staff Member's Full Profile](docs/playbooks/view-staff-profile.md) | Staff | [RU](docs/playbooks/view-staff-profile.ru.md) · [ES](docs/playbooks/view-staff-profile.es.md) · [HI](docs/playbooks/view-staff-profile.hi.md) · [AR](docs/playbooks/view-staff-profile.ar.md) |\n| 13 | [Enhance Student Profile](docs/playbooks/enhance-student-profile.md) | Student | [RU](docs/playbooks/enhance-student-profile.ru.md) · [ES](docs/playbooks/enhance-student-profile.es.md) · [HI](docs/playbooks/enhance-student-profile.hi.md) · [AR](docs/playbooks/enhance-student-profile.ar.md) |\n| 14 | [View Institution Infrastructure](docs/playbooks/view-institution-infrastructure.md) | Institution | [RU](docs/playbooks/view-institution-infrastructure.ru.md) · [ES](docs/playbooks/view-institution-infrastructure.es.md) · [HI](docs/playbooks/view-institution-infrastructure.hi.md) · [AR](docs/playbooks/view-institution-infrastructure.ar.md) |\n| 15 | [View Institution Meals](docs/playbooks/view-institution-meals.md) | Institution | [RU](docs/playbooks/view-institution-meals.ru.md) · [ES](docs/playbooks/view-institution-meals.es.md) · [HI](docs/playbooks/view-institution-meals.hi.md) · [AR](docs/playbooks/view-institution-meals.ar.md) |\n| 16 | [View Student Risk Profile and Welfare Cases](docs/playbooks/view-student-risks.md) | Student | [RU](docs/playbooks/view-student-risks.ru.md) · [ES](docs/playbooks/view-student-risks.es.md) · [HI](docs/playbooks/view-student-risks.hi.md) · [AR](docs/playbooks/view-student-risks.ar.md) |\n| 17 | [View Institution Risk Summary and Alert Rules](docs/playbooks/view-institution-risks.md) | Institution | [RU](docs/playbooks/view-institution-risks.ru.md) · [ES](docs/playbooks/view-institution-risks.es.md) · [HI](docs/playbooks/view-institution-risks.hi.md) · [AR](docs/playbooks/view-institution-risks.ar.md) |\n\n### New in v1.2.0 (OpenEMIS Core 5.13.0)\n\n- **List-filtering via the native `IN` operator (POCOR-9660).** `_conditions=<field>:IN(1,2,3)` filters any field by a value list — including non-PK and composite-PK resources — so a class roster is one call: query `institution-class-students` by `institution_class_id`, then `security-users` with `_conditions=id:IN(101,102,103)`. `params.ids=\"1,2,3\"` now collapses to a single `?id=1,2,3` round-trip **by default** (set `OPENEMIS_CORE_IN_OPERATOR=off` only for pre-5.10 cores).\n- **Stricter filter validation (POCOR-9697).** Filtering on a field that does not exist on a resource now returns HTTP 400 instead of being silently ignored — use exact field names from the [Resource Reference](docs/resources.md).\n- **3 new read-only Runtime resources (POCOR-9694):** `tasks`, `task-jobs`, `task-failures` — the OpenEMIS Runtime queue / job / failure projection. **678 resources · 3,361 endpoints** total.\n\n### New in v1.1.0 (OpenEMIS Core 5.10.0)\n\nLoaded via `openemis_get_playbook` — full English content in `data/playbooks.json`. Translations and per-playbook markdown docs land in a follow-up release.\n\n| # | Playbook | Domain | What it does |\n|---|---|---|---|\n| 18 | `diagnose-alert-delivery` | Alerts | Answer \"did this alert actually go out?\" — walks the POCOR-9509 dispatch pipeline. |\n| 19 | `view-school-accreditation` | Institution | Read institution-accreditations records (POCOR-9610), derive Active/Expired/Future status. |\n| 20 | `view-school-registration` | Institution | Read institution-registrations history with valid_from..valid_to windows. |\n| 21 | `view-institution-budget` | Institution | List institution-budgets per academic period, resolve budget types. |\n| 22 | `query-student-absence-history` | Attendance | Aggregate absences via institution-student-absences + absence-days. |\n| 23 | `query-user-activity-audit-log` | Security | Query the POCOR-9697 user_activities per-field audit trail. |\n| 24 | `view-class-roster` | Institution | Walk institution-classes → institution-class-students → student details. |\n| 25 | `view-admission-and-enrolment-queue-state` | Workflow | Answer \"where is this future student in the admission/enrolment queue?\" — resolves status_id → workflow_step name, current assignee, full transition history. |\n| 26 | `explain-workflow-system` | Workflow | Primer for \"why does this approval take 4 steps?\" — explains workflow_models, steps, statuses, transitions, role-based assignees, and why the plugin makes approval chains configurable per tenant. |\n\n### Write / auth playbooks (stubs — install [mcp-pro](https://github.com/tixuz/openemis-mcp-pro))\n\n`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` — all redirect agents to **[openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro)**, which ships `openemis_create` / `openemis_update` / `openemis_delete` and per-user authentication.\n---\n\n## Core compatibility\n\nTested against **OpenEMIS Core 5.13.0** (master, June 2026). 5.7 – 5.12 deployments are also supported — the public REST surface is backwards-compatible.\n\n### Capability flag — POCOR-9660 multi-id GET\n\n`openemis_get` accepts `params.ids = \"1,2,3\"` for batch lookups. Core 5.10+ carries POCOR-9660 (`?id=1,2,3` support in `CrudApiController`), so the handler collapses the batch into a single round-trip **by default**. Pointing at an older Core (5.7 – 5.9) that lacks the native operator? Force the legacy parallel fan-out:\n\n```bash\nOPENEMIS_CORE_IN_OPERATOR=off\n```\n\nFor composite-PK or view resources — where `ids` does not apply — use `_conditions=<field>:IN(1,2,3)` instead; it filters any field by a value list and works regardless of this flag.\n\n## Architecture\n\n```\nAgent (Claude / Cursor / Codex / …)\n        │ MCP stdio\nopenemis-mcp  ←  6 read tools + 26 read playbooks + 14 redirect stubs\n        │ HTTPS + Bearer JWT\nOpenEMIS Core API  /api/v5/{resource}   (3,361 endpoints across 678 resources)\n```\n\nDomain-scoped discovery keeps conversations small — `openemis_discover(\"attendance\")` returns the 20–30 endpoints relevant to attendance, not all 3,361.\n\n> 🖥️ **Server / HTTP mode** (install once on Oracle, connect from anywhere including ChatGPT) is available in **[openemis-mcp-pro](https://github.com/tixuz/openemis-mcp-pro)**.\n\n---\n\n## Docs\n\n- [Resource Reference](docs/resources.md) — all 678 resources with method availability (Core 5.13.0)\n- [Playbooks](docs/playbooks/) — 17 view playbooks in 5 languages + 9 newer English-only playbooks (translations follow)\n- [GLOSSARY.md](docs/GLOSSARY.md) — key terms: OpenEMIS, MCP, attendance, student risks, and more\n- [FAQ.md](docs/FAQ.md) — common questions about school management with OpenEMIS MCP\n- [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md) — the AI team that built this\n\n---\n\n## Licence\n\n[MIT](LICENSE.md) © 2026 Khindol Madraimov\n\n*Not affiliated with OpenEMIS or its maintainers. Third-party bridge to the public Core API. Credentials stay on your machine.*\n",
  "bytes": 18137,
  "sha": "f12ed6b2758c979ae96adb6055c754f5969a511f2af18384905bf3a07476592e",
  "repo_slug": "tixuz/openemis-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tixuz_openemis_d58e48eb/readme"
}