openemis-mcp

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

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

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 (code P1002) has 553 currently enrolled students."

No code. No JSON. Just ask.

---

What's included (free, MIT)

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)	✅	✅	✅	✅
27 curated playbooks + translations	✅	✅	✅	✅
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)

... View full README on GitHub