moodle-mcp

Model Context Protocol (MCP) Server für Moodle. Ermöglicht KI-Agenten das Veröffentlichen und Verwalten von pädagogischen Inhalten — Lektionen, Ressourcen, Aktivitäten — in Moodle über Web Services mit garantierter Idempotenz.

Status: v0.1 MVP.

Was es ist

moodle-mcp ist ein stdio-basierter MCP-Server, der eine kleine Menge an High-Level-Fassaden sowie ein Low-Level-ws_raw-Primitiv bereitstellt, um eine kanonische pädagogische "Ficha" (eine Markdown-Datei mit YAML-Frontmatter) als echte Abschnitte, Seiten, Ressourcen und Aktivitäten in einem Moodle-Kurs zu veröffentlichen. Jeder Schreibvorgang erfolgt per Upsert über die idnumber, sodass das erneute Veröffentlichen derselben Ficha niemals Duplikate erzeugt.

Primärer Nutzer: Claude Desktop, das den Italicia Sprachlern-Workflow steuert. Es ist jedoch ein generischer Open-Source-Adapter — jeder MCP-fähige Agent + jede Moodle 4.x/5.x-Instanz mit aktivierten Web Services kann ihn verwenden.

In v0.1 verfügbare Werkzeuge

Nicht in v0.1 (geplant für v0.2+): publicar_ficha_examen, sync_alumnos_csv, HTTP/SSE-Transport, GIFT-Builder, Multipart-Asset-Upload, automatische Modulerstellung.

Installation

# Via npx (recommended for Claude Desktop)
npx -y @marcosnahuel/moodle-mcp

# Or install globally
npm install -g @marcosnahuel/moodle-mcp

Erfordert Node.js 20 oder höher.

Konfiguration (Umgebungsvariablen)

Claude Desktop Konfiguration

Fügen Sie dies zu claude_desktop_config.json hinzu (siehe examples/setup-claude-desktop.md für den genauen Pfad je Betriebssystem):

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": ["-y", "moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle.example.com",
        "MOODLE_WS_TOKEN": "your-ws-token"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die fünf oben genannten Werkzeuge sollten nun für den Agenten verfügbar sein.

Beispiele

1. Snapshot eines Kurses vor einer Aktion

// tool call
{
  "name": "obtener_contexto_curso",
  "arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}

Antwort (gekürzt):

{
  "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 }
}

2. Veröffentlichen einer FichaClase (zuerst Vorschau)

{
  "name": "publicar_preview",
  "arguments": {
    "ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
    "course_id": 42
  }
}

Die Antwort enthält eine preview_url, die Alicia öffnen kann, um sie zu überprüfen. Sobald genehmigt:

{
  "name": "confirmar_preview",
  "arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}

3. Notausgang — Aufruf einer rohen WS-Funktion

{
  "name": "ws_raw",
  "arguments": {
    "function_name": "core_webservice_get_site_info",
    "params": {}
  }
}

Antwort:

{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }

Idempotenz

Jede von diesem MCP erstellte Ressource trägt eine stabile idnumber in der Form:

mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>

Das erneute Veröffentlichen derselben Ficha findet die existierende Ressource anhand der idnumber und aktualisiert sie an Ort und Stelle. Nichts wird dupliziert. Sicher, jederzeit und überall erneut zu versuchen.

v0.1 Einschränkungen

v0.1 ist ehrlich bezüglich seiner Funktionsgrenzen. Es kann zuverlässig:

• Einen Kurs, seine Abschnitte und Module nachschlagen.

• "Eigene" Ressourcen anhand des mcp:-Präfixes der idnumber finden.

• Die Sichtbarkeit bereits existierender Module aktualisieren (der Vorschau → Bestätigen-Workflow).

• Strukturierte Moodle-Fehler mit stabilen code-Feldern anzeigen.

• Niemals Token protokollieren, niemals Stack-Traces weitergeben.

v0.1 kann bisher nicht:

• Asset-Dateien via Multipart in den Moodle-Entwurfsbereich hochladen. Geplante Aufrufe für den Asset-Upload werden in advertencias gemeldet — laden Sie diese beim ersten Mal manuell hoch.

• Brandneue Abschnitte oder Module über Web Services erstellen. Wenn ein Modul noch nicht existiert, gibt das Werkzeug den Status "missing" plus eine advertencia zurück. Die Installation von local_wsmanagesections (oder Äquivalent) und die Anbindung dieser Endpunkte ist Arbeit für v0.2.

Beide Lücken werden durch die Integrations-Suite in tests/integration/ abgedeckt, wenn sie gegen ein echtes Moodle-Docker ausgeführt wird.

Entwicklung

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 -v

Sicherheit

• Das Token wird niemals protokolliert. Token, die in irgendeinem Feld eines Protokolleintrags erscheinen, werden durch *** ersetzt.

• URLs in Fehlermeldungen werden ebenfalls geschwärzt.

• HTTPS ist erforderlich, es sei denn, MOODLE_ALLOW_INSECURE=true ist gesetzt (nur für die Entwicklung).

• Das MCP kommuniziert nur über Web Services REST mit Moodle. Keine Cookie-Authentifizierung, kein Web-Scraping, kein direkter Datenbankzugriff.

Mitwirken

Siehe CONTRIBUTING.md für Konventionen zu Issues, PRs und Commits.

Durch die Teilnahme an diesem Projekt erklären Sie sich damit einverstanden, den CODE_OF_CONDUCT.md einzuhalten.

Lizenz

MIT © 2026 Italicia — siehe LICENSE.