Servidor del Protocolo de Contexto de Modelo (MCP) para Moodle. Permite a los agentes de IA publicar y gestionar contenido pedagógico —lecciones, recursos, actividades— en Moodle a través de servicios web con idempotencia garantizada.
Estado: v0.1 MVP.
moodle-mcp es un servidor MCP basado en stdio que expone un pequeño conjunto de fachadas de alto nivel más una primitiva de bajo nivel ws_raw para publicar una "Ficha" pedagógica canónica (un archivo markdown con frontmatter YAML) en un curso de Moodle como secciones, páginas, recursos y actividades reales. Cada escritura es una actualización (upsert) mediante idnumber, por lo que volver a publicar la misma Ficha nunca crea duplicados.
Consumidor principal: Claude Desktop impulsando el flujo de trabajo de enseñanza de idiomas de Italicia. Pero es un adaptador genérico de código abierto: cualquier agente compatible con MCP + cualquier instancia de Moodle 4.x/5.x con servicios web habilitados puede usarlo.
Related MCP server: Moodle MCP Server
Herramienta | Propósito |
| Instantánea de un curso: metadatos, secciones, lecciones publicadas recientemente por MCP, recuentos de matriculaciones. |
| Publicar una FichaClase (ruta absoluta de markdown) como una sección de Moodle + actualizaciones de módulos. |
| Igual que el anterior pero forzado a oculto + devuelve una URL de vista previa. |
| Hacer que una sección previamente oculta y sus módulos sean visibles para los estudiantes. |
| Puerta de escape: llamar a cualquier función de WS de Moodle directamente. |
No incluido en la v0.1 (planificado para la v0.2+): publicar_ficha_examen, sync_alumnos_csv, transporte HTTP/SSE, constructor GIFT, carga de activos multipart, creación automática de módulos.
# Via npx (recommended for Claude Desktop)
npx -y @marcosnahuel/moodle-mcp
# Or install globally
npm install -g @marcosnahuel/moodle-mcpRequiere Node.js 20 o superior.
Variable | Requerido | Predeterminado | Descripción |
| sí | — | URL HTTPS completa de la instancia de Moodle. |
| sí | — | Token de servicios web con permisos de edición. |
| no |
| Tiempo de espera por solicitud. |
| no |
| Intentos de reintento en fallos transitorios. |
| no |
| Límite de tasa de token-bucket. |
| no |
|
|
| no |
| Permitir URLs |
Añadir a claude_desktop_config.json (ver examples/setup-claude-desktop.md para la ruta exacta por SO):
{
"mcpServers": {
"moodle": {
"command": "npx",
"args": ["-y", "moodle-mcp"],
"env": {
"MOODLE_URL": "https://your-moodle.example.com",
"MOODLE_WS_TOKEN": "your-ws-token"
}
}
}
}Reinicia Claude Desktop. Las cinco herramientas anteriores deberían estar ahora disponibles para el agente.
// tool call
{
"name": "obtener_contexto_curso",
"arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}Respuesta (abreviada):
{
"course": { "id": 42, "fullname": "Italiano A1", "shortname": "ITA-A1", "format": "topics", "startdate": 1700000000 },
"secciones": [{ "id": 100, "name": "Unidad 3", "section": 3, "visible": true, "modules_count": 6 }],
"ultimas_clases": [{ "seccion_id": 100, "seccion_name": "Unidad 3", "ficha_idnumber": "mcp:a9993e364706816aba3e2571" }],
"matriculados": { "total": 18, "docentes": 1, "alumnos": 17 }
}{
"name": "publicar_preview",
"arguments": {
"ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
"course_id": 42
}
}La respuesta incluye preview_url que Alicia puede abrir para revisar. Una vez aprobada:
{
"name": "confirmar_preview",
"arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}{
"name": "ws_raw",
"arguments": {
"function_name": "core_webservice_get_site_info",
"params": {}
}
}Respuesta:
{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }Cada recurso creado por este MCP lleva un idnumber estable con la forma:
mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>Volver a publicar la misma Ficha encuentra el recurso existente por idnumber y lo actualiza en su lugar. Nada se duplica. Es seguro volver a intentarlo en cualquier lugar y en cualquier momento.
La v0.1 es honesta sobre su límite de capacidad. De forma fiable:
Busca un curso, sus secciones y módulos.
Encuentra recursos "propios" mediante el prefijo de idnumber mcp:.
Actualiza la visibilidad de módulos preexistentes (el flujo de trabajo vista previa → confirmar).
Muestra errores estructurados de Moodle con campos code estables.
Nunca registra tokens, nunca propaga seguimientos de pila (stack traces).
La v0.1 todavía no:
Sube archivos de activos mediante multipart al área de archivos temporales de Moodle. Las llamadas planificadas para la carga de activos se informan en advertencias: agrégalos manualmente la primera vez.
Crea secciones o módulos nuevos a través de servicios web. Cuando un módulo aún no existe, la herramienta devuelve el estado "missing" más una advertencia. Instalar local_wsmanagesections (o equivalente) y conectar esos puntos finales es trabajo para la v0.2.
Ambas brechas se detectan mediante el conjunto de integración en tests/integration/ cuando se ejecuta contra un Moodle docker real.
git clone https://github.com/marcosnahuel/moodle-mcp
cd moodle-mcp
npm install
npm run typecheck # tsc --noEmit
npm test # vitest unit suite
npm run test:coverage # with v8 coverage (≥80% enforced)
npm run build # tsup → dist/
# Integration — requires docker
docker compose -f tests/integration/docker-compose.test.yml up -d
export MOODLE_TEST_URL=http://localhost:8081
export MOODLE_TEST_TOKEN=<generate in Moodle admin>
export MOODLE_TEST_COURSE=<course id>
npm run test:integration
docker compose -f tests/integration/docker-compose.test.yml down -vEl token nunca se registra. Los tokens que aparecen en cualquier campo de cualquier registro de log se reemplazan por ***.
Las URLs en los mensajes de error también se redactan.
Se requiere HTTPS a menos que MOODLE_ALLOW_INSECURE=true (solo para desarrollo).
El MCP solo se comunica con Moodle a través de REST de servicios web. Sin autenticación por cookies, sin web scraping, sin acceso directo a la base de datos.
Consulta CONTRIBUTING.md para conocer las convenciones de problemas, PR y confirmaciones.
Al participar en este proyecto, aceptas cumplir con el CODE_OF_CONDUCT.md.
MIT © 2026 Italicia — ver LICENSE.
Make a previewed section (and optionally a subset of its modules) visible to students. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| seccion_id | Yes | ||
| recursos_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses idempotency (a key behavioral trait) and the optional nature of 'recursos_ids'. However, it misses critical details like required permissions, whether changes are reversible, or potential side effects on student access, which are important for a visibility-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence plus a note on idempotency—with zero wasted words. It front-loads the core action ('Make visible') and efficiently covers key aspects. Every element earns its place, making it highly readable and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks details on permissions, error conditions, return values, or how visibility changes affect students. For a tool that modifies student access, this leaves significant gaps in understanding its full impact and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 mentions 'seccion_id' and 'recursos_ids' (modules subset) but provides no semantic context—e.g., what a 'seccion_id' represents or how 'recursos_ids' relate to modules. This adds minimal value beyond the bare schema, failing to adequately address the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Make visible') and resource ('previewed section'), specifying the action of revealing content to students. It distinguishes from siblings like 'publicar_preview' by focusing on confirming visibility rather than initial publishing. However, it doesn't explicitly differentiate from all siblings, keeping it at 4 instead of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a section is previewed and needs to be made visible, with optional module selection via 'recursos_ids'. It mentions idempotency, suggesting safe repeated use. However, it lacks explicit when-not-to-use guidance or clear alternatives among siblings like 'publicar_ficha_clase', leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a compact radiograph of a Moodle course: metadata, sections with module counts, recent MCP-published lessons, and enrolment counts (teachers vs students). Call this before publishing a Ficha so the agent knows where it fits.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| incluir_ultimas_clases | No |
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 describes the tool as a read-only operation ('returns') and specifies the scope of data returned, which is helpful. However, it doesn't mention potential limitations like permissions needed, error conditions, or rate limits, leaving some behavioral aspects unclear for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and follows with a clear usage guideline. Every sentence adds value without redundancy, making it efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description provides good context on purpose and usage. It explains what the tool returns and when to use it, which is sufficient for a read-only tool. However, without an output schema or annotations, it could benefit from more details on return format or error handling, slightly limiting completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for undocumented parameters. It explains the purpose of the tool's output but doesn't directly describe the parameters. However, the context ('compact radiograph of a Moodle course') and the parameter names ('course_id', 'incluir_ultimas_clases') are intuitive, and the description implies the tool fetches course-specific data, adding some semantic value. Since there are only 2 parameters, this partial compensation earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('returns a compact radiograph') and resources ('Moodle course'), detailing exactly what information is provided (metadata, sections with module counts, recent MCP-published lessons, enrolment counts). It distinguishes this tool from siblings by explaining its preparatory role for publishing a Ficha, making it highly specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Call this before publishing a Ficha so the agent knows where it fits'), providing clear context and purpose. It distinguishes it from sibling tools by positioning it as a preparatory step for publishing operations, offering specific guidance on its role in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a FichaClase markdown file as a Moodle section with component modules. Idempotent: republishing the same Ficha updates in place, never duplicates. Default modo is oculto (hidden). Use publicar_preview + confirmar_preview for the preview workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| ficha_path | Yes | ||
| course_id | Yes | ||
| section_id | No | ||
| modo | No | oculto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses idempotency ('republishing the same Ficha updates in place, never duplicates'), default behavior ('Default modo is `oculto`'), and workflow relationships. It doesn't mention error conditions or permissions, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each essential: first states purpose, second covers idempotency and default, third provides workflow guidance. No wasted words, front-loaded with core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool with no annotations or output schema, the description is strong but not fully complete: it explains key behaviors (idempotency, defaults, workflow) but lacks details on error handling, response format, or side effects. Given the complexity, it's above minimum viable but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 explains the 'modo' parameter's default value and meaning ('oculto' means hidden), and implies 'ficha_path' refers to a markdown file. It doesn't detail 'course_id' or 'section_id' semantics, but the tool name and context provide some inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Publish') and resource ('a FichaClase markdown file as a Moodle section with component modules'), distinguishing it from siblings like 'publicar_preview' (preview workflow) and 'confirmar_preview' (confirmation step). It specifies the exact transformation from input to output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides when-to-use guidance: 'Use `publicar_preview` + `confirmar_preview` for the preview workflow' distinguishes this as the final publishing tool versus preview alternatives. It also mentions the default mode ('oculto') as a usage hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a FichaClase in hidden preview mode. Returns the same shape as publicar_ficha_clase plus preview_url the teacher can open to review. Students will not see anything until confirmar_preview is called.
| Name | Required | Description | Default |
|---|---|---|---|
| ficha_path | Yes | ||
| course_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a mutation tool (implied by 'Publish'), returns a specific shape (similar to 'publicar_ficha_clase' plus a 'preview_url'), and has side effects (creating a hidden preview accessible only to teachers). However, it lacks details on permissions, error handling, or rate limits, which are important for a mutation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured in two sentences. The first sentence states the core action and return value, while the second clarifies the preview state and next steps. Every word earns its place, with no redundancy or fluff, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation with preview functionality), no annotations, no output schema, and low schema coverage, the description does a good job covering the core behavior and workflow. It explains the preview mode, return shape, and relationship to 'confirmar_preview'. However, it misses details like error cases or the exact return structure, which could be important for agent invocation without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters with 0% description coverage, so the schema provides no semantic information. The description does not explain what 'ficha_path' or 'course_id' represent, their formats, or constraints beyond the schema's basic types. It adds no parameter-specific meaning, but since there are only 2 parameters, the baseline is slightly higher than minimal, though it fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Publish a FichaClase in hidden preview mode') and resource ('FichaClase'), distinguishing it from sibling tools like 'publicar_ficha_clase' (which likely publishes publicly) and 'confirmar_preview' (which confirms the preview). It explicitly mentions the preview mode and the target audience (teacher vs. students), making the purpose distinct and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: for publishing in 'hidden preview mode' that teachers can review, and it specifies an alternative ('confirmar_preview') for making it visible to students. It also implies when not to use it (e.g., for direct student access or final publication without preview), offering clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: call any Moodle Web Services function with arbitrary parameters. Returns { data } on success, structured meta.code + isError: true on failure. Prefer high-level facades when they cover your use case.
| Name | Required | Description | Default |
|---|---|---|---|
| function_name | Yes | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses the return shape: 'Returns `{ data }` on success, structured `meta.code` + `isError: true` on failure,' giving agents a concrete expectation of both success and error behavior. The 'escape hatch' metaphor additionally signals that this tool bypasses typical facades, though it does not detail potential side effects or validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two tightly crafted sentences. The first front-loads the core purpose, and the second packs in return format and usage guidance. There is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic escape-hatch tool, the description covers the essentials: what it does, when to prefer alternatives, and the shape of success/failure responses. It could also warn that function calls are not validated and may have destructive effects, but the 'escape hatch' label and the nudge toward high-level facades partially cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 by explaining parameter meaning. It only says 'with arbitrary parameters,' which essentially repeats the free-form nature of the `params` object already visible in the schema. It does not explicitly state that `params` are passed directly to the Moodle function or how they map to function arguments, leaving a significant gap for a tool that is inherently parameter-driven.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Escape hatch: call any Moodle Web Services function with arbitrary parameters,' which clearly and specifically identifies the tool's purpose and scope. This distinguishes it from high-level sibling tools that each target a single Moodle operation, positioning ws_raw as a generic passthrough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing sentence, 'Prefer high-level facades when they cover your use case,' gives explicit guidance on when to use this tool versus the alternatives. It also labels the tool an 'escape hatch,' which implies it should be a fallback option, not the first choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0confirmar_previewobtener_contexto_cursopublicar_ficha_clasepublicar_previewws_rawScored across 5 tools
Each tool has a distinct and non-overlapping purpose: obtener_contexto_curso provides course metadata, publicar_ficha_clase publishes a class file, publicar_preview publishes in hidden mode, confirmar_preview makes previews visible, and ws_raw serves as a low-level escape hatch. The descriptions clearly differentiate their roles, with no ambiguity in selection.
Naming is inconsistent with mixed conventions: obtener_contexto_curso and publicar_ficha_clase use Spanish verbs with snake_case, while confirmar_preview and publicar_preview mix Spanish verbs with English terms, and ws_raw is an English abbreviation. There is no uniform pattern across the tool set, making it chaotic and harder to predict.
With 5 tools, the count is well-scoped for the server's purpose of managing Moodle courses. Each tool serves a specific function in the publishing workflow (e.g., preview, confirmation, raw access), and none feel redundant or missing for the apparent scope, making the set appropriately sized.
The tool set covers core workflows for publishing and managing Moodle course content, including metadata retrieval, publishing with preview options, and confirmation. A minor gap exists in lacking direct update or deletion tools for existing content, but agents can work around this using the idempotent publishing tools and the ws_raw escape hatch for other operations.
Connect your Moodle to AI assistants: courses, content, grading and reports from the chat.
Create, edit, translate, and export SCORM eLearning modules from a connected AI assistant.
AI-powered LMS course builder: 89 tools, 17 skills, SCORM/xAPI export, agentic UI
Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.
