Skip to main content
Glama

moodle_math_mcp

MCP server for moodle.math.tusur.ru — automates Moodle interactions via Playwright browser automation.

Features

  • list_courses — get available courses

  • list_course_modules — list materials and assignments in a course

  • find_course_module — search modules by title

  • get_assignment_details — fetch assignment page text

  • download_module_files — download files from a resource or assignment

Related MCP server: Moodle MCP Server

Prerequisites

  • Node.js >= 18

  • Playwright browsers: npx playwright install chromium

Setup

  1. Clone the repo:

    git clone https://github.com/<you>/moodle_math_mcp.git
    cd moodle_math_mcp
  2. Install dependencies:

    npm install
  3. Create .env from the example:

    cp .env.example .env

    Fill in MATH_USERNAME and MATH_PASSWORD with your Moodle credentials.

  4. (Optional) Save browser session for cookie-based auth:

    npm run login

    A browser window will open — log in manually. The session is saved to storage/auth.json.

Usage

As an MCP server

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "moodle-math": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/moodle_math_mcp"
    }
  }
}

Development

npm run dev

Build

npm run build
npm start

Environment Variables

Variable

Required

Default

Description

MATH_USERNAME

Yes

Moodle login

MATH_PASSWORD

Yes

Moodle password

MOODLE_URL

No

https://moodle.math.tusur.ru

Moodle base URL

HEADLESS

No

false

Run browser without UI

License

ISC

Available Tools

6 tools
download_course_filesA

Скачать все файлы со всего курса math Moodle целиком (resource + assign)

ParametersJSON Schema
NameRequiredDescriptionDefault
courseUrlYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of explaining behavior. It discloses the main action and scope (download all course files, including resource and assignment files), but it does not mention whether files are packaged, how the download is returned, or any limitations or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence that leads with the core operation and scope. It is concise, though slightly redundant with 'all files' and 'entirely', and the wording is a bit awkward.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no annotations, so the description should explain more about what the agent can expect after invoking the tool. It provides the core scope but omits return behavior, packaging, prerequisites, and any edge-case details, leaving too much to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage and the description does not explain the courseUrl parameter at all. Although the parameter name and URI format give some clue, the description does not compensate for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Скачать' / download), names the resource ('all files from the entire course'), and specifies the included activity types ('resource + assign'). This clearly distinguishes it from sibling tools like download_module_files or list_courses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'all files from the entire course' provides clear context for when to use this tool: when a full-course download is needed. It does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_module_filesC

Скачать файлы только из одного конкретного модуля math Moodle: resource или assign

ParametersJSON Schema
NameRequiredDescriptionDefault
moduleUrlYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains scope but does not state what happens after download (saving, zipping, returning links), any permissions required, or how module files are selected. The description adds minimal behavior beyond the action itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the core action and scope. No wasted words, though it is terse enough that some behavioral and parameter details are omitted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should clarify return values and runtime behavior, but does not. The tool appears simple (one parameter), yet key context like expected input URL format and download outcome is missing, making it incomplete for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the moduleUrl parameter beyond the schema's existing 'uri' type. It leaves unclear how to obtain the URL, what exact URL is expected, or how it relates to resource/assign module pages, so the description fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a clear verb ('Скачать' / download), a resource (files from a single specific module), and narrows scope to 'resource или assign' module types. It also implicitly distinguishes itself from sibling download_course_files by emphasizing 'only from one specific module'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'только из одного конкретного модуля' implies a condition: use this for module-level downloads rather than course-wide downloads. However, it does not explicitly mention alternative tools or provide when-not-to-use guidance, leaving selection partially to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_course_moduleB

Найти материал или задание на странице курса math Moodle по названию

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
courseUrlYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavior disclosure. 'Find' implies a read-only action but the description does not state that nothing is modified, what the return value looks like, or how matching by name behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler and the core action is front-loaded. It is concise, though slightly under-specified for a tool with no annotations or output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without annotations or an output schema, this description is too sparse: it omits return format, matching behavior, error cases, and how this tool relates to siblings like list_course_modules or download_module_files. An agent can guess intent but cannot fully predict outcomes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies that 'по названию' corresponds to the query parameter and the course page context corresponds to courseUrl. It does not explain query format, exact versus partial matching, or other parameter constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (find), resource (material or assignment), location (course page), and search criterion (by title/name). It does not explicitly contrast with list_course_modules, but the 'by name' search semantics help distinguish it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'find ... by name' implies this tool is for locating a specific known material or assignment. However, it never states when not to use it or names alternatives like list_course_modules for browsing all materials.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_assignment_detailsB

Открыть страницу задания в math Moodle и вернуть текст задания

ParametersJSON Schema
NameRequiredDescriptionDefault
assignmentUrlYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. It does disclose that the tool opens a page and returns the assignment text, implying a read-like retrieval. However, it does not state whether it is read-only, what happens on failure, or whether any page session state is affected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, succinct sentence that front-loads the action and outcome. There is no filler, redundant phrasing, or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool with one required URL parameter and no output schema, the description is mostly sufficient: it identifies the input, the operation, and the return value. It could add notes about authentication or error behavior, but these are minor gaps for such a simple fetch-style tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage and the tool description does not mention the assignmentUrl parameter or explain its expected format. The property name and uri format are self-explanatory to some degree, but the description itself adds no parameter semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action—'open the assignment page in math Moodle and return the assignment text'—and identifies a specific resource (the assignment page in math Moodle). It is not a tautology of the tool name and is distinct enough from sibling tools that handle course/file listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance about when to use this tool versus siblings such as list_courses or download_module_files. It only implies use when assignment text is needed, with no exclusions, prerequisites, or alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_course_modulesC

Получить список материалов и заданий на странице курса math Moodle

ParametersJSON Schema
NameRequiredDescriptionDefault
courseUrlYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only list operation and indicates the result type, but it does not disclose authentication needs, response shape, pagination, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no filler. The key verb, object, and scope are front-loaded, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter list operation the description is usable, but with no output schema and no annotations it lacks return-structure details and does not relate to sibling tools. It says what the tool returns, but not in what form or when to prefer it over find_course_module.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema defines only courseUrl as a required URI with 0% description coverage. The phrase 'на странице курса ... Moodle' adds context that the URL should point to a Moodle course page, but it does not explicitly define the parameter or its expected format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb ('Получить' / get) and a clear object: a list of materials and assignments on a Moodle course page. It is distinct enough from siblings like list_courses and get_assignment_details, though it does not explicitly mention 'modules' from the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance about when to choose this tool over siblings such as find_course_module or download_module_files. The description only states what the tool returns, leaving selection criteria to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_coursesA

Получить список курсов из moodle.math.tusur.ru

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the read operation without mentioning whether authentication is required, whether only courses accessible to the current user are returned, whether pagination exists, or what the response items contain. The word 'list' implies read-only behavior, but explicit context is absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no filler or repetition. It is front-loaded with the core action and resource and is appropriately sized for a parameterless list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only listing operation, the description provides the essential context: what to call and where the data comes from. It does not describe return fields, pagination, or authentication expectations, and there is no output schema to fill that gap, but the low complexity keeps this from being a major deficiency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero properties, so there are no parameter semantics for the description to explain. Per the rubric, a parameterless tool receives a baseline of 4 because no parameter documentation burden exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Получить список' / 'get list') and resource ('курсов' / 'courses') plus a concrete source (moodle.math.tusur.ru). It is easily distinguished from siblings like list_course_modules, get_assignment_details, and download_course_files, which target different resources or actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to use this tool instead of the alternatives. It does not mention that it is the entry point before listing course modules or downloading files, nor does it state any exclusions or prerequisites such as authentication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observeddownload_course_files
    • First observeddownload_module_files
    • First observedfind_course_module
    • First observedget_assignment_details
    • First observedlist_course_modules
    • First observedlist_courses

TDQS

A3.5/5.0

Scored across 6 tools

Disambiguation4/5

Most tools are clearly distinct: list_courses, list_course_modules, find_course_module, and the two download tools each target different actions or scopes. get_assignment_details could be slightly confused with download_module_files when an assignment contains files, but its purpose of returning the assignment text is distinguishable.

Naming Consistency5/5

All tool names follow the same lowercase snake_case verb_noun pattern: list_, get_, find_, download_. The naming consistently reflects the action and target resource, making the API predictable.

Tool Count5/5

Six tools is a well-scoped size for a Moodle math file/material retrieval server. Each tool covers a meaningful operation without unnecessary fragmentation or bloat.

Completeness4/5

The set covers the core workflow: listing courses, viewing course modules, finding specific modules, getting assignment details, and downloading files at module or course level. Minor gaps exist, such as no direct way to fetch course metadata or handle other Moodle activities, but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Moodle learning management systems through the Moodle REST API. Supports course management, user enrollment, assignments, forums, quizzes, and file operations through natural language.
    8
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Moodle learning management systems through the REST API. Supports course management, user enrollment, assignment handling, and forum operations through natural language.
    8
    MIT