Wilma MCP Server

Ein MCP (Model Context Protocol)-Server für Wilma – die finnische Schulkommunikationsplattform von Visma. Er ermöglicht Claude und anderen MCP-kompatiblen KI-Assistenten die Interaktion mit Schuldaten, einschließlich Stundenplänen, Nachrichten und mehr.

Funktionen

• Stundenplan – Tägliche oder wöchentliche Stundenpläne mit Fächern, Zeiten und Lehrkräften anzeigen

• Nachrichten – Posteingangsnachrichten mit gelesen/ungelesen-Status abrufen, vollständigen Inhalt anzeigen, als gelesen markieren

• Empfänger – Verfügbare Nachrichtenempfänger auflisten (Lehrkräfte, Personal)

• Nachrichten senden – Nachrichten an Lehrkräfte verfassen und senden

Related MCP server: Dnevnik.ru MCP Server

Voraussetzungen

• Python 3.11 oder höher

• Ein Wilma-Konto (Schüler, Erziehungsberechtigter oder Lehrkraft)

• Die Wilma-URL Ihrer Schule (z. B. https://yourschool.inschool.fi)

Installation

# Clone the repository
git clone https://github.com/jessemc98/wilma-mcp.git
cd wilma-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Konfiguration

Erstellen Sie eine .env-Datei mit Ihren Wilma-Anmeldedaten:

cp .env.example .env

Bearbeiten Sie .env:

WILMA_BASE_URL=https://yourschool.inschool.fi
WILMA_USERNAME=your_username
WILMA_PASSWORD=your_password

Sicherheitshinweis: Committen Sie Ihre .env-Datei niemals in die Versionskontrolle.

Verwendung mit OpenClaw

Wenn Sie OpenClaw verwenden, enthält dieses Projekt eine SKILL.md, die Ihrem Agenten automatisch beibringt, wie er die Wilma MCP-Tools verwendet.

1. Führen Sie die obigen Schritte Installation und Konfiguration aus.

2. Fügen Sie den MCP-Server zu Ihren Claude Code-Einstellungen hinzu (~/.claude.json oder Projekt-.mcp.json):

{
  "mcpServers": {
    "wilma": {
      "command": "/path/to/wilma-mcp/venv/bin/python",
      "args": ["-m", "wilma_mcp.server"],
      "cwd": "/path/to/wilma-mcp"
    }
  }
}

3. Platzieren oder verlinken Sie die SKILL.md in Ihrem OpenClaw-Skills-Verzeichnis, damit der Agent sie finden kann.

Verwendung mit Claude Desktop

Fügen Sie den Server zu Ihrer Claude Desktop-Konfigurationsdatei hinzu:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wilma": {
      "command": "/path/to/wilma-mcp/venv/bin/python",
      "args": ["-m", "wilma_mcp.server"],
      "cwd": "/path/to/wilma-mcp"
    }
  }
}

Starten Sie Claude Desktop nach der Aktualisierung der Konfiguration neu.

Verfügbare Tools

get_schedule

Ruft den Schulstundenplan für ein bestimmtes Datum ab.

Parameter:

• date_str (optional): Datum, für das der Stundenplan abgerufen werden soll. Standardmäßig "today".

  • Unterstützt: "today", "tomorrow", "yesterday"

  • Wochentagsnamen: "monday", "tuesday", usw. (Englisch oder Finnisch)

  • Datumsformate: "2024-03-15", "15.3.2024"

Beispiel: "Wie sieht mein Stundenplan für Montag aus?"

get_week_schedule

Ruft den Stundenplan für eine ganze Woche ab.

Parameter:

• start_date (optional): Startdatum der Woche. Standardmäßig heute.

Beispiel: "Zeig mir den Stundenplan für nächste Woche"

get_messages

Ruft eine Liste der Nachrichten aus dem Posteingang ab. Jede Nachricht zeigt einen gelesen/ungelesen-Indikator (📖 gelesen, 📬 ungelesen).

Parameter:

• folder (optional): Ordnername – "inbox", "sent", "archive" oder "drafts". Standardmäßig "inbox".

• limit (optional): Maximale Anzahl zurückzugebender Nachrichten. Standardmäßig 20.

Bei "sent" und "drafts" zeigt die Auflistung den Empfänger ("An:") anstelle des Absenders.

Beispiel: "Überprüfe meine Nachrichten" / "Zeig mir meine gesendeten Nachrichten"

get_message

Liest eine bestimmte Nachricht mit vollständigem Inhalt. Hinweis: Das Anzeigen einer Nachricht markiert sie automatisch als gelesen auf dem Wilma-Server.

Parameter:

• message_id: Die ID der zu lesenden Nachricht.

Beispiel: "Lies Nachricht 12345"

set_message_read

Markiert eine Nachricht explizit als gelesen. Nützlich, um Nachrichten als gelesen zu markieren, ohne ihren vollständigen Inhalt zu lesen. Wilma unterstützt das Markieren von Nachrichten als ungelesen nicht – dies ist eine Plattformbeschränkung.

Parameter:

• message_id: Die ID der als gelesen zu markierenden Nachricht.

Beispiel: "Markiere Nachricht 12345 als gelesen"

get_recipients

Ruft eine Liste der verfügbaren Nachrichtenempfänger ab (Lehrkräfte, Personal, Erziehungsberechtigte).

Parameter:

• query (optional): Groß-/Kleinschreibung-unabhängiger Namensfilter (z. B. der Nachname einer Lehrkraft). Praktisch, da die vollständige Empfängerliste einer Schule lang sein kann.

Jeder zurückgegebene Empfänger hat eine id-Zeichenfolge (z. B. r_guardian=11876_2893&n_class=33), die Sie direkt an send_message übergeben können.

Beispiel: "Wem kann ich Nachrichten senden?" / "Finde den Empfänger für Herrn Schmidt"

send_message

Sendet eine neue Nachricht an einen beliebigen Empfänger (Lehrkraft, Mitarbeiter oder Erziehungsberechtigten).

Parameter:

• recipient: An wen gesendet werden soll – entweder der Name einer Person (z. B. "Galiana Fatima", wird automatisch gegen die Empfängerliste aufgelöst) oder eine Empfänger-id von get_recipients (z. B. "r_guardian=11876_2893&n_class=33"). Um mehrere Personen zu adressieren, verbinden Sie ihre IDs mit &.

• subject: Nachrichtenbetreff

• body: Nachrichtentext/-inhalt

Wenn ein Name mit mehr als einer Person übereinstimmt, gibt das Tool die Liste der Übereinstimmungen zurück, damit Sie eine bestimmte ID auswählen können (es wird nicht geraten).

Beispiel: "Sende eine Nachricht an Herrn Schmidt bezüglich der Hausaufgaben"

Um auf eine vorhandene Nachricht zu antworten, verwenden Sie stattdessen reply_to_message – es löst den Empfänger automatisch aus der ursprünglichen Nachricht auf.

reply_to_message

Antwortet auf eine vorhandene Nachricht. Dies ist die bevorzugte Methode zum Antworten, da sie die Empfängerauflösung automatisch über das Wilma-Antwortformular handhabt, ohne dass Empfänger-IDs nachgeschlagen werden müssen.

Parameter:

• message_id: ID der Nachricht, auf die geantwortet werden soll (von get_messages)

• body: Antwortnachrichtentext/-inhalt

Beispiel: "Antworte auf Nachricht 12345, dass ich teilnehmen werde"

Beispielunterhaltungen

Nach der Konfiguration können Sie Claude fragen:

• "Wie sieht mein Stundenplan für heute aus?"

• "Habe ich am Freitag Unterricht?"

• "Zeig mir meine ungelesenen Nachrichten"

• "Lies die Nachricht von meiner Lehrkraft"

• "Um wie viel Uhr beginnt die Schule morgen?"

Technische Hinweise

• Wilma hat keine offizielle öffentliche API. Dieser Server rekonstruiert die Webschnittstelle.

• Die Authentifizierung verwendet Sitzungscookies, die über den Anmeldevorgang erhalten werden.

• Stundenplandaten werden aus eingebettetem JavaScript auf der Stundenplanseite extrahiert.

• Nachrichtenlisten verwenden JSON-Endpunkte pro Ordner (/messages/list für den Posteingang, /messages/list/outbox für gesendet, /messages/list/archive, /messages/list/drafts); einzelne Nachrichten erfordern HTML-Parsing.

• Gelesen/ungelesen-Verfolgung: Wilmas JSON-API enthält ein Status-Feld pro Nachricht – truthy bedeutet ungelesen, falsy/abwesend bedeutet gelesen. Das Anzeigen einer Nachricht (GET-Anfrage) markiert sie serverseitig als gelesen. Es gibt keine API, um eine Nachricht als ungelesen zu markieren.

• Nachrichten senden: Wilma stellt Empfänger nicht als <option>-Elemente dar. Der Empfängerauswähler (/messages/recipients) bettet jede erreichbare Person als .recipient-block ein, dessen data-source-Link einen Selektor der Form r_<type>=<id> kodiert (z. B. r_guardian, r_personnel, r_ownteachers). Zum Verfassen führt der Server ein GET auf /messages/compose?<selector> aus (das das Formular mit einem neuen formkey und dem Empfänger, der als versteckte r_<type>-Eingabe vorausgefüllt ist, zurückgibt), füllt die Felder Subject und BodyText aus und sendet ein POST mit dem addsavebtn "Senden"-Button. Deshalb funktionieren jetzt neue Nachrichten, nicht nur Antworten.

• Der Server muss möglicherweise aktualisiert werden, wenn sich die Webschnittstelle von Wilma ändert.

Entwicklung

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Zukünftige Funktionen (Geplant)

• Noten und Bewertungen

• Fehlzeiten/Anwesenheitsaufzeichnungen

• Bevorstehende Prüfungen

• Schulnachrichten/Ankündigungen

• Kurslisten

Lizenz

MIT-Lizenz – siehe LICENSE-Datei.

Haftungsausschluss

Dies ist ein inoffizielles Projekt und steht in keiner Verbindung zu Visma und wird von Visma nicht unterstützt. Nutzung auf eigene Gefahr. Bitte respektieren Sie die Nutzungsbedingungen und Ratenbegrenzungen von Wilma.

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.