moodle-mcp-server — Análisis de LMS impulsado por IA

Pregúntale cualquier cosa a tu instancia de Moodle. Obtén respuestas estructuradas en segundos.

moodle-mcp-server es un servidor MCP (Protocolo de Contexto de Modelo) de código abierto que conecta agentes de IA directamente a la API de Servicios Web de Moodle. Es el conector de Moodle detrás del trabajo más amplio de CSMediaPro sobre la Capa de Consulta Agente (AQL).

En lugar de aprender constructores de informes, escribir SQL o exportar CSV, haces preguntas en lenguaje natural — el agente de IA consulta tu LMS y devuelve datos estructurados.

Página del proyecto: https://csmediapro.com/products/moodle-mcp-server Paquete npm: https://www.npmjs.com/package/moodle-mcp-server-aql Registro MCP: io.github.csmediapro/moodle-mcp-server-aql

Características

• Herramientas de consulta principales — catálogo de cursos, inscripción de usuarios, tareas, navegación por categorías, metadatos del sitio, búsqueda de usuarios y gestión de caché

• Complementos de informes premium — herramientas opcionales como informes de finalización de cursos y actividad reciente se pueden adjuntar a través del tiempo de ejecución de complementos

• Independiente del LLM — funciona con Claude, GPT, Gemini, Ollama o cualquier cliente de IA compatible con MCP

• Modificación cero del LMS — utiliza la API existente de Servicios Web de Moodle, no requiere instalación de complementos

• Manejo de datos preparado para cumplimiento — procesamiento de datos seguro y eficiente con privacidad por diseño

• Solo lectura — nunca modifica los datos de Moodle, seguro para producción

• Extensible mediante complementos — coloca nuevos módulos de herramientas en un directorio; las herramientas y las sugerencias opcionales de enrutamiento de agentes se registran automáticamente en tiempo de ejecución

Related MCP server: Moodle MCP Server

Inicio rápido

Requisitos previos

• Node.js 20+

• Una instancia de Moodle con Servicios Web habilitados

• Un token de API de Moodle (Administración del sitio → Complementos → Servicios web → Gestionar tokens)

Uso con un Cliente MCP

La mayoría de los usuarios inician el servidor a través de un cliente MCP como Claude Desktop:

{
  "mcpServers": {
    "moodle-mcp-server-aql": {
      "command": "npx",
      "args": ["-y", "moodle-mcp-server-aql"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.example",
        "MOODLE_TOKEN": "your-moodle-web-services-token"
      }
    }
  }
}

Configuración desde el Código Fuente

# Clone the repo
git clone https://github.com/csmediapro/moodle-mcp-server
cd moodle-mcp-server

# Install dependencies
npm install

# Configure
cp packages/server/.env.example packages/server/.env
# Edit .env: add your MOODLE_URL and MOODLE_TOKEN

# Run (stdio mode)
npm run server:build
node packages/server/dist/index.js

Esquema de campos de usuario

La configuración de visualización de campos de usuario se genera por instancia de Moodle y se almacena localmente en packages/server/data/user-field-schema.json. Este archivo es intencionalmente ignorado por git porque puede incluir campos de perfil personalizados específicos del sitio.

Después de conectarte a un sitio de Moodle, ejecuta la herramienta refresh_user_field_schema una vez para descubrir los campos de usuario estándar y personalizados disponibles. Se incluye un ejemplo de forma mínima en packages/server/data/user-field-schema.example.json.

El complemento user-directory almacena una caché de usuario completo normalizada con campos de perfil personalizados aplanados en claves de nivel superior como school. Una vez que existe esa caché, list_users puede filtrar usuarios en caché en memoria, y summarize_user_directory_field puede devolver valores distintos y recuentos en caché. Por ejemplo, "mostrar escuelas únicas" o "mostrar escuelas y número de usuarios asignados a cada una" resume el campo en caché school sin otra recuperación de Moodle.

Identidad de configuración

El núcleo posee dos campos de identidad de servidor diferentes:

• server.id — identidad de máquina estable, por ejemplo mcp_8f3k2q9x

• server.name — etiqueta de visualización para humanos

Si falta server.id, el núcleo genera uno una vez y lo persiste en el archivo de configuración resuelto antes de que continúe el inicio.

Anulaciones de entorno:

• MOODLE_MCP_CONFIG o MOODLE_MCP_SERVER_CONFIG — elige la ruta del archivo de configuración

• SERVER_ID — anulación explícita de server.id

• SERVER_NAME — anulación explícita de server.name

• SERVER_VERSION — anulación explícita de server.version

Si falta server.id y la ruta de configuración resuelta no es escribible, el inicio falla deliberadamente.

Uso del cliente de referencia

# From the project root
cp packages/client/.env.example packages/client/.env
npm run client:dev
# Open http://localhost:3000

El cliente detectará automáticamente tu instancia de Moodle y presentará una interfaz de chat donde puedes hacer preguntas en lenguaje natural.

Conexión de un LLM

moodle-mcp-server necesita un modelo de IA para potenciar la interfaz de lenguaje natural. Tú aportas el modelo — el núcleo de moodle-mcp-server y el cliente de referencia admiten cualquier proveedor compatible con MCP.

Opción 1: Ejecutar Localmente (Recomendado por Velocidad y Privacidad)

Ejecutar un modelo local mantiene todos los datos en tu propio hardware — nada sale de tu red. Los modelos cuantizados modernos funcionan bien en GPUs de consumo e incluso en configuraciones solo con CPU.

Rendimiento: Un modelo cuantizado de 24B en una sola RTX 3090 ofrece respuestas de ~1.5 segundos después de la primera consulta — más rápido que la mayoría de las APIs en la nube una vez que el sistema está inicializado.

Vía Ollama (más fácil)

# Install Ollama: https://ollama.com
ollama pull gemma3:12b      # Fast, reliable tool use (~200ms TTFT)
ollama pull qwen3:14b       # Strong reasoning, good for complex queries
ollama pull deepseek-r1:14b # Excellent at multi-step chains

Luego apunta el cliente de referencia a http://localhost:11434 (el valor predeterminado de Ollama).

Vía llama.cpp (máximo control)

# Download a GGUF model (example: Devstral 24B Q4)
# Run the llama.cpp server:
llama-server -m devstral-24b-Q4_K_M.gguf --ctx-size 60000 --port 8080

Apunta el cliente de referencia a http://localhost:8080/v1.

Modelos locales recomendados

Opción 2: Proveedores en la Nube

Anthropic (Claude):

export ANTHROPIC_API_KEY=sk-ant-...

Selecciona "Anthropic" en el menú desplegable de proveedores del cliente de referencia. Claude Sonnet ofrece el comportamiento de llamada a herramientas más fiable.

OpenAI (GPT):

export OPENAI_API_KEY=sk-...

Selecciona "OpenAI" en el menú desplegable de proveedores. GPT-4o funciona bien en consultas estructuradas.

Ollama Cloud: Utiliza la misma API que Ollama local, alojada en https://ollama.com/v1. Buen punto intermedio — más rápido que los arranques en frío locales, más privado que los grandes proveedores de la nube.

Opción 3: Claude Desktop (MCP Directo)

Claude Desktop se conecta al núcleo de moodle-mcp-server directamente a través de stdio — no se necesita cliente de referencia.

Añade a tu configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "moodle-mcp-server": {
      "command": "node",
      "args": ["/path/to/moodle-mcp-server/packages/server/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_TOKEN": "your-api-token"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas del servidor aparecerán en la lista de herramientas de Claude — haz preguntas directamente.

Herramientas

Herramientas principales (gratuitas, código abierto — AGPL)

Complementos Premium (disponibles por separado)

• Informes Avanzados — libros de calificaciones, comparación entre cursos, constructor de informes personalizado

• Analítica de Usuarios — seguimiento de progreso, puntuación de compromiso, indicadores de riesgo

• Directorio de Usuarios — listado de directorio en caché y filtrado estructurado a través de campos de perfil estándar y personalizados

• Paquete de Cumplimiento — seguimiento de certificaciones, alertas de vencimiento, exportaciones de auditoría

Arquitectura

User (plain English question)
    │
    ▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
    │
    ▼  MCP Protocol
`moodle-mcp-server`
    ├── Tool Registry (core + plugins)
    ├── Agent Runtime Config (core + plugin rules)
    ├── Optimized Data Layer (secure, efficient data handling)
    └── Moodle Client (REST API calls)
    │
    ▼
Moodle Web Services API

Modos de transporte

• Stdio — dist/index.js — se ejecuta como un subproceso, utilizado por Claude Desktop y clientes similares

El núcleo OSS se envía intencionalmente solo con stdio. Cualquier envoltura orientada a la red, supervisión remota o adjunto de complemento premium pertenece a un agente de nodo comercial separado o envoltura.

Documentación de complementos

• Contrato de Complemento

• Creación de Complementos

• Ejemplo de Complemento Hola

Licencia

AGPL v3 — consulta LICENSE.

Esto significa que puedes:

• ✅ Usar el núcleo de moodle-mcp-server de forma gratuita, en cualquier entorno

• ✅ Modificar el código fuente para tus necesidades

• ✅ Construir y distribuir trabajos derivados

No puedes:

• ❌ Reempaquetar el núcleo de moodle-mcp-server como un producto comercial competidor de código cerrado

• ❌ Ofrecerlo como un servicio de red sin compartir tus modificaciones

Aviso de Marca Comercial

Moodle es una marca comercial de Moodle Pty Ltd. moodle-mcp-server es un proyecto independiente de CSMediaPro y no está afiliado, respaldado, patrocinado ni conectado oficialmente con Moodle Pty Ltd o el proyecto Moodle. El nombre se usa de manera descriptiva para identificar la compatibilidad con Moodle LMS.

Construido por CSMediaPro

moodle-mcp-server es construido y mantenido por CSMediaPro, una empresa de desarrollo de software especializada en integración de IA, ingeniería de sistemas y automatización de flujos de trabajo.

• Contacto: contact@csmediapro.com