Read tools¶
Scope read and capability local/mcp:read (by default, every authenticated user). Each tool also respects what the user can see in Moodle.
General¶
site_info¶
Returns the site name, release and the user the token acts as.
No parameters.
Returns: site (fullName, shortName, wwwRoot, release, branch), user (id, username, fullName), plugin (component, release, version, writeEnabled), scopes. server (php, database) only for users with moodle/site:config.
Example arguments:
search_courses¶
Searches courses by name, short name, id number or summary. Only courses the user can see are returned.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | no | "" |
Text to match (max 255). |
limit |
integer | no | 20 |
Maximum rows (1–50). |
offset |
integer | no | 0 |
Rows to skip. |
Returns: total, courses[] (id, shortName, fullName, categoryId, visible, idNumber).
Moodle permissions: Course visibility for the user.
Example arguments:
get_course_structure¶
Returns the sections of a course and the activities in each one that the user can see.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
Returns: courseId, fullName, shortName, format, sections[] (id, section, name, summary, visible, activities[]).
Moodle permissions: Access to the course.
Example arguments:
list_participants¶
Lists enrolled participants and their roles. Email is included only with identity permission.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
limit |
integer | no | 50 |
Maximum rows (1–200). |
offset |
integer | no | 0 |
Rows to skip. |
Returns: courseId, total, participants[] (id, username, fullName, roles; email only with moodle/site:viewuseridentity).
Moodle permissions: moodle/course:viewparticipants. Groups are respected unless the user has moodle/site:accessallgroups.
Example arguments:
list_activities¶
Lists the activities of a course, optionally filtered by type or section.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
type |
string | no | — | Module name, e.g. page, assign, quiz. |
section |
integer | no | — | Section number. Omit for all visible sections. |
Returns: courseId, activities[].
Moodle permissions: Access to the course.
Example arguments:
get_grades_summary¶
Summarises grade items. Class averages follow the course's user-report "show average" setting and moodle/grade:viewall. The enrolment count is only returned to someone who can view all grades.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
userId |
integer | no | — | User id. Needs permission to view all grades unless it is the current user. |
Returns: courseId, canViewAll, enrolled (null unless the user can view all grades), items[] (itemId, name, type, module, gradeMax; average and gradedCount when class averages are allowed; the user's finalGrade and percentage).
Moodle permissions: moodle/grade:view; moodle/grade:viewall for averages and other users; hidden grades need moodle/grade:viewhidden.
Example arguments:
get_task_status¶
Reads a background task queued by this server (a course copy from create_course or a build_course run).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
taskId |
integer | yes | — | Id returned when the task was queued. |
Returns: taskId, taskType, status (pending, running, finished, failed); courseId when finished; error when failed.
Moodle permissions: Only the user who queued the task, or a site administrator. Anyone else gets the same not-found error as a missing id.
Example arguments:
Student¶
Tools named get_my_* return only the current user's own data.
get_my_deadlines¶
Deadlines for the current user between two times, from calendar action events. Only activities the user can see. Status is pending or submitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
from |
integer | no | now |
Range start (Unix timestamp). |
to |
integer | no | from + 30 days |
Range end. |
courseId |
integer | no | — | Limit to one course the user can open. |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: from, to, deadlines[] (with course and URL).
Moodle permissions: Calendar action events for that user; activity visibility.
Example arguments:
get_my_grades¶
The current user's grades and feedback. Hidden items and grades hidden by a lock are omitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | no | — | One course. Omit for every enrolled course. |
Returns: courses[].
Moodle permissions: moodle/grade:view in each course.
Example arguments:
get_my_progress¶
The current user's activity completion in a course. Hidden and unavailable activities are omitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
Returns: courseId, enabled, completed, total, activities[].
Moodle permissions: Access to the course.
Example arguments:
get_assignment_details¶
Assignment description, due date, rubric or marking guide, and the current user's own submission status. Other users' submissions are not returned.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
cmid |
integer | yes | — | Assignment course module id. |
Returns: cmid, name, dueDate, status, submitted, plus the brief and rubric or guide when configured.
Moodle permissions: mod/assign:view.
Example arguments:
get_forum_posts¶
Latest posts in a forum, including the announcements forum. Posts hidden by groups, availability or visibility are omitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
cmid |
integer | yes | — | Forum course module id. |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: cmid, name, posts[].
Moodle permissions: mod/forum:viewdiscussion.
Example arguments:
get_calendar_events¶
Upcoming calendar events: site events and events in courses the user can open. Hidden events are omitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
from |
integer | no | now |
Range start. |
to |
integer | no | from + 30 days |
Range end. |
courseId |
integer | no | — | Limit course events to this course (site events still included). |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: events[].
Moodle permissions: Calendar visibility.
Example arguments:
search_course_content¶
Searches visible pages, labels and resources in a course. Uses Moodle global search when enabled; otherwise matches names, introductions and page or label content.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
query |
string | yes | — | Text to search (2–200). |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: courseId, engine, results[].
Moodle permissions: Visible activities only.
Example arguments:
Teacher¶
Each tool checks the reporting or grading capability below. A user without it gets an error or an empty list.
get_submissions_status¶
Submission status for one assignment: submitted, not submitted and waiting for a grade. Separate groups are respected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
cmid |
integer | yes | — | Assignment course module id. |
limit |
integer | no | 50 |
Maximum rows (1–200). |
Returns: cmid, participants, submitted, needsGrading, notSubmitted[].
Moodle permissions: mod/assign:grade (moodle/site:accessallgroups to see all groups).
Example arguments:
get_ungraded_work¶
Assignments and quizzes waiting for a grade in courses where the user can grade. A user with no grading capability gets an empty list.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | no | — | One course. Omit to scan every enrolled course. |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: activities[] (with a pending count and the oldest submission).
Moodle permissions: mod/assign:grade, mod/quiz:grade.
Example arguments:
get_quiz_results¶
Average quiz grade (scaled to the quiz maximum) and the questions most often missed. Separate groups are respected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
cmid |
integer | yes | — | Quiz course module id. |
Returns: cmid, attempts, average, questions[].
Moodle permissions: mod/quiz:viewreports.
Example arguments:
get_inactive_students¶
Students with no course access in the given number of days, or completion below completionBelow. Separate groups are respected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
days |
integer | no | 14 |
Days without access (1–365). |
completionBelow |
integer | no | — | Also include users below this completion percent (0–100). |
limit |
integer | no | 50 |
Maximum rows (1–200). |
offset |
integer | no | 0 |
Rows to skip. |
Returns: courseId, total, students[].
Moodle permissions: moodle/course:viewparticipants and report/outline:view.
Example arguments:
get_activity_completion_report¶
Completed and incomplete counts per activity. Separate groups are respected; hidden activities are omitted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
Returns: courseId, enabled, activities[].
Moodle permissions: report/progress:view.
Example arguments:
get_course_logs_summary¶
Counts of recent course log events from the standard log store, grouped by component. In separate groups only events from visible users are counted.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
days |
integer | no | 7 |
Days back (1–90). |
Returns: courseId, events, components[].
Moodle permissions: report/log:view.
Example arguments:
get_forum_unanswered¶
Discussions with no replies in the course forums the user can see. Group and availability restrictions apply.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
courseId |
integer | yes | — | Moodle course id. |
limit |
integer | no | 20 |
Maximum rows (1–50). |
Returns: courseId, discussions[].
Moodle permissions: mod/forum:viewdiscussion.
Example arguments: