About ictexam-mcp
ictexam-mcp connects AI assistants to the ICTExam exam platform for teachers and administrators. It provides read access to exams, gradebooks, and item analysis; paper parsing and publishing are available only when writes are enabled.
Key features
- 01List exams, classes, and subjects
- 02Read exam settings and questions
- 03Retrieve gradebooks and student marks
- 04View per-question difficulty and averages
- 05Optional paper parsing and publishing
Use cases
- 01Review exam status and question settings
- 02Check class exam results
- 03Analyze question difficulty and marks
- 04Parse and publish a PDF or DOCX paper
MCP support
The MCP server connects to the ICTExam REST API using an account session and exposes exam and grade-reading tools to MCP clients. Write tools are not registered by default; set ICTEXAM_MCP_ALLOW_WRITE=true to enable them.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y ictexam-mcpICTEXAM_BASE_URLBase URL of your ICTExam site, e.g. https://app.ictlms.net (no trailing /api).ICTEXAM_EMAILA teacher or admin account email.ICTEXAM_PASSWORDSecretPassword for the account.ICTEXAM_API_PREFIXPath the API is mounted under. Defaults to /api (behind the usual reverse proxy). Set empty to talk to the backend port directly.ICTEXAM_MCP_ALLOW_WRITEUnlocks the write tools: parse a paper with AI (spends server AI credit), publish and unpublish exams. When false these tools are not registered at all. Leave off unless you mean it.ICTEXAM_TIMEOUT_MSPer request timeout in milliseconds. Defaults to 60000 (AI parsing can be slow).ICTEXAM_TLS_INSECURESkip TLS certificate verification. Only for a self-signed test server.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
6Saved tool list · updated 2d ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| class_id | integer | No | Optional class id filter. |
| subject_id | integer | No | Optional subject id filter. |
Details
From the project READMEictexam-mcp
A Model Context Protocol server for ICTExam, the AI exam authoring, delivery and auto-grading platform from ICT Innovations.
It lets an AI assistant read your exams, gradebooks and per-question item analysis, and — only when you turn writes on — parse a question paper into a structured exam with AI and publish exams to students.
Install
Run it straight from npm with npx, or install it globally:
npx -y ictexam-mcp # no install
npm install -g ictexam-mcp
Requires Node.js 18 or newer.
Configure
Set these in your MCP client's server config (or a .env):
| Variable | Required | Default | |
|---|---|---|---|
ICTEXAM_BASE_URL | yes | Your site, e.g. https://app.ictlms.net (no trailing /api) | |
ICTEXAM_EMAIL | yes | A teacher or admin account | |
ICTEXAM_PASSWORD | yes | Password for that account | |
ICTEXAM_API_PREFIX | no | /api | API mount path; set empty to hit the backend port directly |
ICTEXAM_MCP_ALLOW_WRITE | no | false | Unlock the write tools (see Safety) |
ICTEXAM_TIMEOUT_MS | no | 60000 | Per-request timeout (AI parsing can be slow) |
ICTEXAM_TLS_INSECURE | no | false | Skip TLS verification — self-signed test servers only |
Claude Desktop example
{
"mcpServers": {
"ictexam": {
"command": "npx",
"args": ["-y", "ictexam-mcp"],
"env": {
"ICTEXAM_BASE_URL": "https://app.ictlms.net",
"ICTEXAM_EMAIL": "[email protected]",
"ICTEXAM_PASSWORD": "your-password"
}
}
}
}
Tools
Read tools are always available:
| Tool | What it does |
|---|---|
ictexam_list_exams | List exam papers (id, title, status, class, subject) |
ictexam_get_exam | One paper's settings, share links and questions |
ictexam_list_classes | Classes (course groups) |
ictexam_list_subjects | Subjects, each tied to a class |
ictexam_gradebook | Per-exam totals and student marks |
ictexam_item_analysis | Per-question difficulty, p-value and average mark |
Write tools appear only when ICTEXAM_MCP_ALLOW_WRITE=true:
| Tool | What it does |
|---|---|
ictexam_parse_question_paper | Upload a local PDF/DOCX and AI-extract the questions |
ictexam_publish_exam | Publish a paper; returns student and teacher share URLs |
ictexam_unpublish_exam | Set a paper back to draft |
Safety
The server is read-only by default. The three write tools are not registered
at all unless you set ICTEXAM_MCP_ALLOW_WRITE=true, so a default install cannot
change anything on the platform. Parsing a paper spends AI credit on the server,
and publishing makes an exam live for students — both sit behind that switch on
purpose. The client authenticates with the account's own session cookie and
echoes the CSRF token on writes, exactly as the web app does; it never stores or
logs your password beyond the environment you give it.
How it connects
ICTExam runs a FastAPI backend. The server signs in once with your email and
password, keeps the session cookie for the life of the process, and talks to the
REST API under /api (configurable). No API key to provision.
About
Built by Tahir Almas at ICT Innovations — the team behind ICTExam, ICTContact, ICTDialer, ICTFax and ICTPBX. ICTExam ships with a native Moodle activity module (LTI 1.3, grade passback and roster sync); learn more at ictlms.net.
MIT licensed. Issues and PRs welcome at github.com/ictinnovations/ictexam-mcp.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.