Tool	What it does
`openemis_health`	Ping the configured instance — real login round-trip
`openemis_list_domains`	List the 9 curated domains (Attendance, Assessment, Staff, Student…)
`openemis_discover`	Topic → up to 30 scoped endpoints. Keeps conversations small
`openemis_list_playbooks`	List all 24 curated workflow guides
`openemis_get_playbook`	Load a playbook by id — full steps, resources, gotcha notes
`openemis_get`	Unified read: list or singleton, any resource, any filter

24 curated playbooks covering attendance, assessment, student profiles, staff profiles, infrastructure, meals, risk dashboards, class reports, timetables, and more — each verified against the v5 manifest at 100% resource coverage.

Translations available: Russian · Spanish · Hindi · Arabic — all 24 playbooks in all four languages.

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

	Free	Individual Pro	Institution Pro	Country Pro
Read tools (all 645 resources)	✅	✅	✅	✅
24 read playbooks × 5 languages	✅	✅	✅	✅
3 write playbooks (v0.2+)	—	✅	✅	✅
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: khindol.madraimov@gmail.com

Install

Requires 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

Configure

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

Smoke test

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

Register with 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"

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.

# 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

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 curated workflow guides — see docs/playbooks/:

#	Playbook	Domain	Translations
1	Count Vacant Positions	Staff	RU · ES · HI · AR
2	Mark Student Attendance	Attendance	RU · ES · HI · AR
3	Mark Staff Attendance	Staff	RU · ES · HI · AR
4	View Student Timetable	Schedule	RU · ES · HI · AR
5	Student Dashboard	Student	RU · ES · HI · AR
6	Generate Student Report Card PDF	Report	RU · ES · HI · AR
7	Enrol a New Student	Student	RU · ES · HI · AR
8	Record a Behaviour Incident	Student	RU · ES · HI · AR
9	Submit Exam Marks	Assessment	RU · ES · HI · AR
10	Institution Summary	Institution	RU · ES · HI · AR
11	Generate Institution Statistics PDF	Report	RU · ES · HI · AR
12	View Latest Attendance	Attendance	RU · ES · HI · AR
13	View Student Profile	Student	RU · ES · HI · AR
14	View Student Marks	Assessment	RU · ES · HI · AR
15	View Class Report	Report	RU · ES · HI · AR
16	View Timetable	Schedule	RU · ES · HI · AR
17	View Full Institution Profile	Institution	RU · ES · HI · AR
18	View Full Class Profile	Student	RU · ES · HI · AR
19	View a Staff Member's Full Profile	Staff	RU · ES · HI · AR
20	Enhance Student Profile	Student	RU · ES · HI · AR
21	View Institution Infrastructure	Institution	RU · ES · HI · AR
22	View Institution Meals	Institution	RU · ES · HI · AR
23	View Student Risk Profile and Welfare Cases	Student	RU · ES · HI · AR
24	View Institution Risk Summary and Alert Rules	Institution	RU · ES · HI · AR

Core compatibility

Tested against OpenEMIS Core 5.9 (master, May 2026). 5.7 and 5.8 deployments are also supported — the public REST surface is unchanged.

Optional capability flag — POCOR-9660 multi-id GET

openemis_get accepts params.ids = "1,2,3" for batch lookups. By default the handler fans out N parallel single-record GETs (Core ≤ 5.9 master has no native multi-id filter). Once a deployment carries POCOR-9660 (?id=1,2,3 support in CrudApiController), set:

OPENEMIS_CORE_IN_OPERATOR=1

The handler then collapses the batch into a single round-trip. Default off — flip on after upstream merge.

Architecture

Agent (Claude / Cursor / Codex / …)
        │ MCP stdio
openemis-mcp  ←  6 read tools + 24 playbooks
        │ HTTPS + Bearer JWT
OpenEMIS Core API  /api/v5/{resource}

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