io.github.tixuz/openemis
Read-only MCP server for OpenEMIS v5 — 645 resources, 24 playbooks, natural-language queries
Ask AI about io.github.tixuz/openemis
Powered by Claude · Grounded in docs
I know everything about io.github.tixuz/openemis. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 has 97 currently enrolled students across 6 classes."
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, anddeleteare 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_resultentries 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/:
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.
🖥️ Server / HTTP mode (install once on Oracle, connect from anywhere including ChatGPT) is available in openemis-mcp-pro.
Docs
- Resource Reference — all 645 resources with method availability
- Playbooks — 24 workflow guides in English, Russian, Spanish, Hindi, and Arabic
- 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.