Read tools

27 read tools: 26 with scope read and search_users. Scope read and capability local/mcpserver:read (by default, every authenticated user), except search_users, which needs the admin scope. Each tool also respects what the user can see in Moodle. Tools that take courseId also accept courseShortname; send only one of the two. Where a tool identifies a person, userId, username and email are alternatives: fill in only one.

This reference is generated from the tool schemas in version 0.8.6. Values listed for format, auth, role and similar fields depend on what the site has enabled.

General

site_info

Return the Moodle site name, release and the user this token acts as.

No parameters.

Returns: site, user, plugin, scopes[], server.

Scope: read. Moodle permissions: None. server details only with moodle/site:config.

Example arguments:

{}

search_courses

Search courses by name, short name or id number. Only courses the current user can see are returned.

Parameter	Type	Required	Default	Description
query	string	no	""	Text to match against the course name, short name, id number or summary. (max. 255)
limit	integer	no	20	Maximum number of rows to return. (1–50)
offset	integer	no	0	Number of rows to skip.

Returns: total, courses[].

Scope: read. Moodle permissions: Course visibility for the user.

Example arguments:

{"query": "statistics", "limit": 5}

list_categories

List course categories visible to the current user. Each row has id, name, idnumber, path, courseCount and canCreate (moodle/course:create in that category). Pass query to filter by name, idnumber or path, and onlyCreatable to keep categories where this user may create a course.

Parameter	Type	Required	Default	Description
query	string	no	""	Optional text matched against the name, idnumber and path.
onlyCreatable	boolean	no	false	When true, only categories where the user may create a course.

Returns: categories[].

Scope: read. Moodle permissions: Category visibility; canCreate reflects moodle/course:create.

Example arguments:

{"onlyCreatable": true}

get_course_structure

Return the sections of a course and the activities in each section that the current user can see.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)

Returns: courseId, sections[].

Scope: read. Moodle permissions: Course access.

Example arguments:

{"courseShortname": "STAT101"}

list_participants

List enrolled participants and their roles. Email is included only with identity permission.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
limit	integer	no	50	Maximum number of rows to return. (1–200)
offset	integer	no	0	Number of rows to skip.

Returns: courseId, total, participants[].

Scope: read. Moodle permissions: moodle/course:viewparticipants (moodle/site:viewuseridentity for email, moodle/site:accessallgroups for every group).

Example arguments:

{"courseId": 42, "limit": 20}

list_activities

List activities in a course. Filter by activity type or section number.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
type	string	no	—	Activity module name, for example page, assign or quiz. (max. 32)
section	integer	no	—	Section number. Omit to include every visible section.

Returns: courseId, activities[].

Scope: read. Moodle permissions: Course access.

Example arguments:

{"courseId": 42, "type": "assign"}

get_grades_summary

Summarise grade items. Class averages follow the 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	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
userId	integer	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email. Optional here. Another person requires moodle/grade:viewall.
username	string	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email. Optional here. Another person requires moodle/grade:viewall. (max. 100)
email	string	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email. Optional here. Another person requires moodle/grade:viewall. (max. 100)

Returns: courseId, canViewAll, items[].

Scope: read. Moodle permissions: moodle/grade:view; moodle/grade:viewall for averages and other users; hidden grades need moodle/grade:viewhidden.

Example arguments:

{"courseId": 42}

get_task_status

Read a background task queued by this server. Status is pending, running, finished or failed. A finished course copy includes the new course id. A failed task includes the error. Only the user who queued the task, or a site administrator, can read it.

Parameter	Type	Required	Default	Description
taskId	integer	yes	—	Id returned when the task was queued.

Returns: taskId, taskType, status, courseId, error.

Scope: read. Moodle permissions: Only the user who queued the task, or a site administrator.

Example arguments:

{"taskId": 7}

get_activity_settings

Read one activity's module form settings and the keys accepted by add_activity and update_activity in settings. settings uses the same names as the activity form, including visible, cmidnumber, groupmode, completion fields and availabilityconditionsjson.

Parameter	Type	Required	Default	Description
cmid	integer	yes	—	Course module id.

Returns: cmid, courseId, type, name, settings, acceptedKeys.

Scope: read. Moodle permissions: moodle/course:manageactivities.

Example arguments:

{"cmid": 314}

Student

get_my_deadlines

Deadlines for the current user between two times, from the calendar action events. Only activities this user can see are included. Status is pending or submitted.

Parameter	Type	Required	Default	Description
from	integer	no	—	Range start as a Unix timestamp. Defaults to now.
to	integer	no	—	Range end as a Unix timestamp. Defaults to 30 days after from.
courseId	integer	no	—	Limit to one course the user can open. Alternative to courseShortname. Send only one of the two.
courseShortname	string	no	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: from, to, deadlines[].

Scope: read. Moodle permissions: That user's calendar action events; activity visibility.

Example arguments:

{"limit": 10}

get_my_grades

Grades and feedback for the current user. Hidden items and grades hidden by a lock are omitted. Only courses the user can open and where they have moodle/grade:view are included.

Parameter	Type	Required	Default	Description
courseId	integer	no	—	One course. Omit to read every enrolled course. Alternative to courseShortname. Send only one of the two.
courseShortname	string	no	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)

Returns: courses[].

Scope: read. Moodle permissions: moodle/grade:view in each course.

Example arguments:

{"courseId": 42}

get_my_progress

Activity completion for the current user. Hidden and unavailable activities are omitted.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)

Returns: courseId, enabled, completed, total, activities[].

Scope: read. Moodle permissions: Course access.

Example arguments:

{"courseId": 42}

get_assignment_details

Assignment description, due date, rubric or marking guide, and the current user's 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.

Scope: read. Moodle permissions: mod/assign:view.

Example arguments:

{"cmid": 314}

get_forum_posts

Latest posts in a forum, including the announcements forum. Posts the user cannot see because of groups, availability or visibility are omitted.

Parameter	Type	Required	Default	Description
cmid	integer	yes	—	Forum course module id.
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: cmid, name, posts[].

Scope: read. Moodle permissions: mod/forum:viewdiscussion.

Example arguments:

{"cmid": 315, "limit": 10}

get_calendar_events

Upcoming calendar events for the current user: site events and events in courses they can open. Hidden events are omitted.

Parameter	Type	Required	Default	Description
from	integer	no	—	Range start. Defaults to now.
to	integer	no	—	Range end. Defaults to 30 days after from.
courseId	integer	no	—	Limit course events to this course. Site events are still included. Alternative to courseShortname. Send only one of the two.
courseShortname	string	no	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: events[].

Scope: read. Moodle permissions: Calendar visibility.

Example arguments:

{"courseId": 42}

search_course_content

Search visible pages, labels and resources in a course. Uses Moodle global search when it is enabled, otherwise matches names, introductions and page or label content.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
query	string	yes	—	Text to search for. (max. 200)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: courseId, engine, results[].

Scope: read. Moodle permissions: Visible activities only.

Example arguments:

{"courseId": 42, "query": "regression"}

Teacher

get_ungraded_work

Assignments and quizzes waiting for a grade in courses where the current user can grade. A user with no grading capability gets an empty list. Separate groups are respected.

Parameter	Type	Required	Default	Description
courseId	integer	no	—	Limit to one course. Omit to scan every course the user is enrolled in. Alternative to courseShortname. Send only one of the two.
courseShortname	string	no	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: activities[].

Scope: read. Moodle permissions: mod/assign:grade, mod/quiz:grade.

Example arguments:

{"courseId": 42}

get_inactive_students

Students (users who appear in completion reports) with no course access in the given number of days, or completion below completionBelow. Requires moodle/course:viewparticipants and report/outline:view. Separate groups are respected.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
days	integer	no	14	No course access for this many days counts as inactive. (1–365)
completionBelow	integer	no	—	Also include users whose tracked completion percent is below this. (0–100)
limit	integer	no	50	Maximum number of rows to return. (1–200)
offset	integer	no	0	Number of rows to skip.

Returns: courseId, total, students[].

Scope: read. Moodle permissions: moodle/course:viewparticipants and report/outline:view.

Example arguments:

{"courseId": 42, "days": 14}

get_submissions_status

Submission status for one assignment: submitted, not submitted and waiting for a grade. Requires mod/assign:grade. Separate groups are respected.

Parameter	Type	Required	Default	Description
cmid	integer	yes	—	Assignment course module id.
limit	integer	no	50	Maximum number of rows to return. (1–200)

Returns: cmid, participants, submitted, needsGrading, notSubmitted[].

Scope: read. Moodle permissions: mod/assign:grade (moodle/site:accessallgroups to see every group).

Example arguments:

{"cmid": 314}

get_submission

Read one student's assignment submission: plain online text, files (with text from txt, md, html and simple PDFs), status, date, attempt, current grade, feedback comment, and the rubric or marking guide with the chosen levels. Identify the student with userId, username or email, and only one of them. Requires mod/assign:grade. Separate groups and blind marking are respected.

Parameter	Type	Required	Default	Description
cmid	integer	yes	—	Assignment course module id.
userId	integer	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email.
username	string	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email. (max. 100)
email	string	no	—	One of three alternative ways to identify the same user. Fill in only one of userId, username or email. (max. 100)

Returns: cmid, courseId, name, userId, fullName, status, submitted, attempt, timeModified, onlineText, files[], grade, gradeMax, gradeTime, comment, grading.

Scope: read. Moodle permissions: mod/assign:grade (mod/assign:viewblinddetails to see identities under blind marking).

Example arguments:

{"cmid": 314, "username": "ada"}

get_quiz_results

Average quiz grade (scaled to the quiz maximum) and the questions most often missed. Requires mod/quiz:viewreports. Separate groups are respected.

Parameter	Type	Required	Default	Description
cmid	integer	yes	—	Quiz course module id.

Returns: cmid, attempts, average, questions[].

Scope: read. Moodle permissions: mod/quiz:viewreports.

Example arguments:

{"cmid": 316}

get_activity_completion_report

Completed and incomplete counts per activity for users in the completion report. Requires report/progress:view. Separate groups are respected. Hidden activities are omitted.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)

Returns: courseId, enabled, activities[].

Scope: read. Moodle permissions: report/progress:view.

Example arguments:

{"courseId": 42}

get_course_logs_summary

Counts of recent course log events from the standard log store, grouped by component. Requires report/log:view. In separate groups only events from visible users are counted.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
days	integer	no	7	How many days back to read. (1–90)

Returns: courseId, events, components[].

Scope: read. Moodle permissions: report/log:view.

Example arguments:

{"courseId": 42, "days": 7}

get_forum_unanswered

Discussions with no replies in the forums of a course that the current user can see. Group and availability restrictions apply.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: courseId, discussions[].

Scope: read. Moodle permissions: mod/forum:viewdiscussion.

Example arguments:

{"courseId": 42}

Messaging

list_conversations

List the current user's Moodle message conversations, including how many messages are unread. Only conversations this user belongs to are returned.

Parameter	Type	Required	Default	Description
limit	integer	no	20	Maximum number of rows to return. (1–50)
offset	integer	no	0	Number of rows to skip.

Returns: conversations[].

Scope: read. Moodle permissions: Only the user's own conversations.

Example arguments:

{"limit": 10}

get_conversation_messages

Read messages in one conversation the current user belongs to. Nothing is marked read unless markAsRead is true. Marking as read needs the write scope and write tools switched on.

Parameter	Type	Required	Default	Description
conversationId	integer	yes	—	Conversation id from list_conversations.
limit	integer	no	20	Maximum number of rows to return. (1–100)
markAsRead	boolean	no	false	When true, mark the conversation read. Requires the write scope and write tools.

Returns: conversationId, markedAsRead, messages[].

Scope: read. Moodle permissions: Membership of the conversation.

Example arguments:

{"conversationId": 17}

Accounts (admin scope)

search_users

Search site accounts by name, username, email or idnumber. Returns id, username, name, email, suspended and last access. Email and idnumber are matched and returned only when this user may see them. Requires the admin scope and moodle/user:viewdetails.

Parameter	Type	Required	Default	Description
query	string	yes	—	Text matched against name, username, and email or idnumber when visible. (max. 100)
limit	integer	no	20	Maximum number of rows to return. (1–50)

Returns: users[].

Scope: admin. Moodle permissions: Scope admin and moodle/user:viewdetails (system).

Example arguments:

{"query": "lovelace"}