Openemis

io.github.tixuzPublished by GitHub account tixuzv1.1.0Updated Oct 24, 2026

Read-only MCP server for OpenEMIS — free open-source school management system. 675 resources.

VerifiedSTDIODesktop onlyKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Read-only MCP bridge that lets an assistant query an OpenEMIS school management system — students, attendance, staff, exams and infrastructure — in plain…

What you can do
  • Check connectivity and list curated domains or playbooks for the configured OpenEMIS instance
  • Discover the endpoints relevant to a topic, keeping responses small
  • Load read-only playbooks with steps, resources and gotcha notes
  • Read any resource, list or single record, with filters and batch ids
  • Cover attendance, assessment, student and staff profiles, infrastructure, meals, risks, timetables, audit logs and admission queue state
When to use it
Useful when you administer or work with an OpenEMIS school instance and want an assistant to answer questions about enrolment, attendance, marks, staffing, risks or infrastructure without writing API calls. It is read-only, so it suits reporting and lookups rather than data entry.
Requirements
Runs locally as a Node.js 22+ process (npm package openemis-mcp) over stdio. Needs the base URL of an OpenEMIS instance plus login credentials: OPENEMIS_BASE_URL, OPENEMIS_USERNAME, OPENEMIS_PASSWORD and OPENEMIS_API_KEY, the API key being issued by the OpenEMIS admin. Network access to the instance is required.
Before you install
It holds school login credentials and an API key in environment variables, so store them carefully. Verbose logging (OPENEMIS_LOG_VERBOSE) writes tool results containing tenant PII such as student names and enrolment details; it is off by default and should only be enabled on instances you own or with consent. Write operations are not available here and are redirected to a separate paid product.

Installation

In SourceWeft

  1. Open Openemis in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

title: "openemis-mcp — AI bridge for OpenEMIS school management" description: "Free, read-only MCP server that connects AI assistants to OpenEMIS school management. Query student attendance, risks, staff, and 678 resources." keywords:

  • OpenEMIS
  • school management system
  • education management
  • student attendance
  • student risks
  • MCP server

[openemis-mcp logo — AI bridge for OpenEMIS school management]

openemis-mcp — AI bridge for OpenEMIS school management

Free, read-only MCP bridge between AI agents and any OpenEMIS school.

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

Built on the published OpenEMIS Core API (reference: api.openemis.org/core) and verified against the public demo at demo.openemis.org/core.

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.

Ask in plain English:

"How many current students are at Avory Primary?"

The agent plans the calls, this MCP delivers the data:

"Avory Primary School has 97 currently enrolled students across 6 classes."

No code. No JSON. Just ask.

What's included (free, MIT)

ToolWhat it does
openemis_healthPing the configured instance — real login round-trip
openemis_list_domainsList the 9 curated domains (Attendance, Assessment, Staff, Student…)
openemis_discoverTopic → up to 30 scoped endpoints. Keeps conversations small
openemis_list_playbooksList all 40 playbooks — 26 read-only here, 14 stubs that redirect to mcp-pro
openemis_get_playbookLoad a playbook by id — full steps, resources, gotcha notes
openemis_getUnified read: list or singleton, any resource, any filter

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 for the actual write/auth steps.

Translations: Русский · Español · हिन्दी · العربية — 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.

✏️ Write operations (creating/updating records in OpenEMIS) require openemis-mcp-pro. This free server is intentionally read-only — post, put, and delete are not available.

What's in Pro

openemis-mcp-pro adds write tools, remote hosting, and ChatGPT compatibility on top of this free read-only server.

FreeIndividual ProInstitution ProCountry Pro
Read tools (all 678 resources, Core 5.13.0)✅✅✅✅
26 read playbooks (17 × 5 languages + 9 EN)✅✅✅✅
14 write / auth playbooks (mark-attendance, enrol, set-accreditation…)stub✅✅✅
stdio mode (Claude Code, Cursor, Cline)✅✅✅✅
HTTP server mode (Oracle / VPS — install once, connect by URL)—✅✅✅
OpenAPI adapter (ChatGPT Custom GPT, any REST client)—✅✅✅
Direct write — single record—✅✅✅
Institution audit trail——✅✅
Workflow route execution——✅✅
Institution-admin approval gate——✅✅
Batch ops within one institution——✅✅
Multi-institution batch ops———✅
Ministry approval gates———✅
Cross-institution oversight———✅

HTTP server mode lets you install Pro once on an Oracle Always 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 for step-by-step setup.

→ Pricing: [email protected]

Install

Requires Node 22+.

bash
git clone https://github.com/tixuz/openemis-mcp.gitcd openemis-mcpnpm installnpm run buildcp .env.example .env$EDITOR .env

Configure

env
OPENEMIS_BASE_URL=https://demo.openemis.org/coreOPENEMIS_USERNAME=adminOPENEMIS_PASSWORD=your_passwordOPENEMIS_API_KEY=your_api_key

Smoke test

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

Register with Claude Code

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

Works with any MCP-compatible client: Claude Code, Cursor, Cline, Codex (via gemmy-and-qwenny), or any stdio MCP client.

Verbose logging (optional)

Capture every tool call and its response as JSONL — useful for debugging, tuning playbooks, or sharing a bug report.

bash
# stderr (visible in your MCP client's log panel)OPENEMIS_LOG_VERBOSE=1 node dist/server.js
# write to a fileOPENEMIS_LOG_VERBOSE=1 OPENEMIS_LOG_FILE=/tmp/openemis.jsonl node dist/server.js

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

⚠️ 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.

🌐 Remote / server install: 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 for how to let teachers mark attendance via ChatGPT.

Playbooks

24 read-only workflow guides — see 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.

Read playbooks (school data lookups)

#PlaybookDomainTranslations
1Count Vacant PositionsStaffRU · ES · HI · AR
2View Student TimetableScheduleRU · ES · HI · AR
3Student DashboardStudentRU · ES · HI · AR
4Institution SummaryInstitutionRU · ES · HI · AR
5View Latest AttendanceAttendanceRU · ES · HI · AR
6View Student ProfileStudentRU · ES · HI · AR
7View Student MarksAssessmentRU · ES · HI · AR
8View Class ReportReportRU · ES · HI · AR
9View TimetableScheduleRU · ES · HI · AR
10View Full Institution ProfileInstitutionRU · ES · HI · AR
11View Full Class ProfileStudentRU · ES · HI · AR
12View a Staff Member's Full ProfileStaffRU · ES · HI · AR
13Enhance Student ProfileStudentRU · ES · HI · AR
14View Institution InfrastructureInstitutionRU · ES · HI · AR
15View Institution MealsInstitutionRU · ES · HI · AR
16View Student Risk Profile and Welfare CasesStudentRU · ES · HI · AR
17View Institution Risk Summary and Alert RulesInstitutionRU · ES · HI · AR

New in v1.2.0 (OpenEMIS Core 5.13.0)

  • 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).
  • 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.
  • 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.

New in v1.1.0 (OpenEMIS Core 5.10.0)

Loaded via openemis_get_playbook — full English content in data/playbooks.json. Translations and per-playbook markdown docs land in a follow-up release.

#PlaybookDomainWhat it does
18diagnose-alert-deliveryAlertsAnswer "did this alert actually go out?" — walks the POCOR-9509 dispatch pipeline.
19view-school-accreditationInstitutionRead institution-accreditations records (POCOR-9610), derive Active/Expired/Future status.
20view-school-registrationInstitutionRead institution-registrations history with valid_from..valid_to windows.
21view-institution-budgetInstitutionList institution-budgets per academic period, resolve budget types.
22query-student-absence-historyAttendanceAggregate absences via institution-student-absences + absence-days.
23query-user-activity-audit-logSecurityQuery the POCOR-9697 user_activities per-field audit trail.
24view-class-rosterInstitutionWalk institution-classes → institution-class-students → student details.
25view-admission-and-enrolment-queue-stateWorkflowAnswer "where is this future student in the admission/enrolment queue?" — resolves status_id → workflow_step name, current assignee, full transition history.
26explain-workflow-systemWorkflowPrimer 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.

Write / auth playbooks (stubs — install 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 — all redirect agents to openemis-mcp-pro, which ships openemis_create / openemis_update / openemis_delete and per-user authentication.

Core compatibility

Tested against OpenEMIS Core 5.13.0 (master, June 2026). 5.7 – 5.12 deployments are also supported — the public REST surface is backwards-compatible.

Capability flag — POCOR-9660 multi-id GET

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:

bash
OPENEMIS_CORE_IN_OPERATOR=off

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

Architecture

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

Domain-scoped discovery keeps conversations small — openemis_discover("attendance") returns the 20–30 endpoints relevant to attendance, not all 3,361.

🖥️ Server / HTTP mode (install once on Oracle, connect from anywhere including ChatGPT) is available in openemis-mcp-pro.

Docs

  • Resource Reference — all 678 resources with method availability (Core 5.13.0)
  • Playbooks — 17 view playbooks in 5 languages + 9 newer English-only playbooks (translations follow)
  • GLOSSARY.md — key terms: OpenEMIS, MCP, attendance, student risks, and more
  • FAQ.md — common questions about school management with OpenEMIS MCP
  • ACKNOWLEDGEMENTS.md — the AI team that built this

Licence

MIT © 2026 Khindol Madraimov

Not affiliated with OpenEMIS or its maintainers. Third-party bridge to the public Core API. Credentials stay on your machine.

Source: README.md at commit f88a80f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.