Write tools

36 tools that change data or need write mode: 26 with scope write and 10 with scope admin. Scope write (or admin) and capability local/mcpserver:write (local/mcpserver:admin for admin tools). Write mode must be on and the tool enabled; otherwise write tools are not listed. See Enabling write mode. Account tools (create_user, create_users, update_user, suspend_user, unsuspend_user) and site policy tools (set_site_policy_handler, create_policy, update_policy, list_policies, get_policy_acceptances) need the admin scope. list_policies and get_policy_acceptances only read, but they are admin tools and need write mode too. Each tool also checks the Moodle capability below.

Most write tools accept dryRun. delete_activity, delete_section and grade_submission are dry runs by default; see Grading with dryRun. Dates accept YYYY-MM-DD (midnight in the user's timezone), an ISO 8601 datetime with an offset, or a Unix timestamp.

Courses and activities

create_course

Create a blank course, or queue a background copy when templateCourseId is set. A template copy returns a task id and status immediately; poll get_task_status. Choose the category with categoryId, categoryName or categoryIdnumber. Pass dryRun true to validate without creating a course or queueing a task.

Parameter	Type	Required	Default	Description
fullName	string	yes	—	Course full name. (max. 254)
shortName	string	yes	—	Unique course short name. (max. 255)
categoryId	integer	no	1	Category id. Defaults to 1. Ignored when categoryIdnumber or categoryName is set.
categoryName	string	no	—	Category name. If several match, the error lists them. Use list_categories. (max. 255)
categoryIdnumber	string	no	—	Category idnumber. Preferred over categoryName and categoryId. (max. 100)
summary	string	no	""	Course summary HTML.
format	string	no	"topics"	Enabled course format.
visible	boolean	no	true	Whether the course is visible to students.
numSections	integer	no	1	Number of sections for a blank course. Ignored when copying a template. (0–52)
startDate	integer or string	no	—	Course start. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
endDate	integer or string	no	—	Course end. 0 means no end date. On a weekly course, sending this date keeps it instead of calculating it from the number of sections. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
templateCourseId	integer	no	—	Course id to copy. Activities are copied. Users are not copied unless includeUserData is true.
includeUserData	boolean	no	false	Copy enrolments and user data from the template. Requires the backup user-info capability.
dryRun	boolean	no	false	When true, check permissions and names but do not create a course or queue a copy.

Returns: courseId, shortName, fullName, url, taskId, status, queued, dryRun.

Scope: write. Moodle permissions: moodle/course:create in the category; a copy also needs moodle/backup:backupcourse and moodle/backup:backuptargetimport (moodle/backup:userinfo with user data).

Example arguments:

{"fullName": "Statistics 102", "shortName": "STAT102", "categoryIdnumber": "SCI", "dryRun": true}

add_section

Add a section at the end of a course and optionally set its name and summary.

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)
name	string	no	—	Section name. Omit to keep the format default. (max. 255)
summary	string	no	""	Section summary HTML.

Returns: courseId, section, name.

Scope: write. Moodle permissions: moodle/course:update.

Example arguments:

{"courseId": 42, "name": "Week 5"}

add_activity

Add a page, url, label, resource, assign, quiz, forum or choice. Each field says which types it applies to, for example [assign] or [url]. A field sent for another type is an error. Assignments accept dates, a maximum grade, submission types and a basic rubric. A resource takes fileUrl or fileBase64 (2 MiB maximum). A label or a page can take images (jpg, png, gif, webp or svg, fileBase64 plus fileName, or an https fileUrl); they are stored in the intro or content area and the HTML uses @@PLUGINFILE@@, never a data URI. Completion fields (view, submit, grade, passing grade, forum posts and the expected date) are accepted only when the module supports them. settings is any other field from the module's form; unknown keys are rejected. A choice accepts settings.option (a list of texts), settings.limit, allowupdate and showresults (0 does not publish the results); completionSubmit marks it complete when the student chooses. Use get_activity_settings to list the form fields.

Parameter	Type	Required	Default	Description
courseId	integer	one of courseId / courseShortname	—	[all] Moodle course id. Alternative to courseShortname. Send only one of the two.
courseShortname	string	one of courseId / courseShortname	—	[all] Exact course short name. Alternative to courseId for the same course. Send only one of the two. (max. 255)
section	integer	yes	—	[all] Section number. Section 0 is the general section.
type	string	yes	—	[all] Activity type. Values: page, url, label, assign, quiz, forum, resource, choice.
name	string	no	—	[all] Activity name. For a label this may be omitted and the intro is used. (max. 255)
intro	string	no	""	[all] Description HTML. This is the body of a label.
content	string	no	—	[page, label] Page HTML content. Also used as the label body when intro is empty.
images	array	no	—	[page, label] Images for a label or a page. Each one is fileBase64 plus fileName, or an https fileUrl, and area intro or content. Stored in the file area and referenced as @@PLUGINFILE@@. (up to 10)
externalUrl	string	no	—	[url] External URL. (max. 1333)
dueDate	integer or string	no	—	[assign] Assignment due date. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
timeOpen	integer or string	no	—	[quiz] Quiz open time. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
timeClose	integer or string	no	—	[quiz] Quiz close time. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
grade	integer	no	—	[assign, quiz] Maximum grade. (0–100000)
forumType	string	no	—	[forum] Forum type. Defaults to general. Values: general, eachuser, single, qanda, blog, news.
visible	boolean	no	—	[all] Whether the activity is visible. Defaults to true.
allowSubmissionsFromDate	integer or string	no	—	[assign] Assignment open date. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
cutoffDate	integer or string	no	—	[assign] Assignment cut-off date. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
gradingDueDate	integer or string	no	—	[assign] Date by which grading should be completed. A date without a time (YYYY-MM-DD) is midnight in your timezone. You can also send an ISO 8601 datetime with an offset, or a Unix timestamp. (date)
submissionTypes	array	no	—	[assign] Submission plugins: file and/or onlinetext. (up to 2)
rubric	array	no	—	[assign] Optional rubric. Each criterion has a description and at least two levels. (up to 20)
fileName	string	no	—	[resource] File name. (max. 255)
fileUrl	string	no	—	[resource] Public http(s) URL of the file. (max. 1333)
fileBase64	string	no	—	[resource] Base64 contents of the file. Maximum 2 MiB decoded.
timeLimit	integer	no	—	[quiz] Time limit in seconds. 0 means no limit.
attempts	integer	no	—	[quiz] Attempts allowed. 0 means unlimited. (0–10)
gradeMethod	string	no	—	[quiz] How the grade is calculated from attempts. Values: highest, average, first, last.
navMethod	string	no	—	[quiz] Navigation: free or sequential. Values: free, sequential.
questionsPerPage	integer	no	—	[quiz] Questions per page. 0 means all on one page. (0–50)
shuffleAnswers	boolean	no	—	[quiz] Shuffle the answers.
review	string	no	—	[quiz] When students may review the attempt. Values: immediately, later, afterclose, never.
settings	object	no	—	[all] Module form options, using the form field names. Unknown keys are rejected and the error lists the valid ones. Includes visible, cmidnumber, groupmode, completion and availabilityconditionsjson.
completionView	boolean	no	—	[all] Require the student to view the activity. The module must support completion views.
completionSubmit	boolean	no	—	[all] Require a submission or a choice. Only modules with the completionsubmit rule, such as assign or choice.
completionUseGrade	boolean	no	—	[all] Require a grade. The module must have a grade.
completionPassGrade	boolean	no	—	[all] Require a passing grade. Send gradePass as well. The module must have a grade.
gradePass	number	no	—	[all] Minimum grade to pass. Required when completionPassGrade is true, and not above the maximum grade.
completionPosts	integer	no	—	[all] Posts the student must publish. Only modules that define completionposts, such as forum. 0 clears it. (0–1000)
completionDiscussions	integer	no	—	[all] Discussions the student must start. Only modules that define completiondiscussions. 0 clears it. (0–1000)
completionReplies	integer	no	—	[all] Replies the student must post. Only modules that define completionreplies. 0 clears it. (0–1000)
completionExpected	integer or string	no	—	[all] Date the activity is expected to be completed. (date)

Fields of each item in rubric:

• description* (string): [assign] What this criterion assesses. (max. 1000)
• levels* (array