Wilma MCP Server

Сервер MCP (Model Context Protocol) для Wilma — финской школьной коммуникационной платформы от Visma. Он позволяет Claude и другим AI-ассистентам, совместимым с MCP, взаимодействовать со школьными данными, включая расписание, сообщения и многое другое.

Возможности

• Расписание — просмотр дневного или недельного расписания с предметами, временем и учителями

• Сообщения — чтение входящих сообщений со статусом прочитано/не прочитано, просмотр полного содержимого, отметка как прочитанное

• Получатели — список доступных получателей сообщений (учителя, сотрудники)

• Отправка сообщений — создание и отправка сообщений учителям

Related MCP server: Dnevnik.ru MCP Server

Предварительные требования

• Python 3.11 или выше

• Учётная запись Wilma (ученик, родитель или учитель)

• URL вашей школы Wilma (например, https://yourschool.inschool.fi)

Установка

# 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 .

Конфигурация

Создайте файл .env с вашими учётными данными Wilma:

cp .env.example .env

Отредактируйте .env:

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

Примечание по безопасности: Никогда не добавляйте файл .env в систему контроля версий.

Использование с OpenClaw

Если вы используете OpenClaw, этот проект включает файл SKILL.md, который автоматически обучает вашего агента работе с инструментами Wilma MCP.

1. Выполните шаги Установка и Конфигурация выше.

2. Добавьте MCP-сервер в настройки Claude Code (~/.claude.json или проект .mcp.json):

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

3. Поместите или создайте символическую ссылку на SKILL.md в каталоге навыков OpenClaw, чтобы агент мог его обнаружить.

Использование с Claude Desktop

Добавьте сервер в файл конфигурации Claude Desktop:

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

Перезапустите Claude Desktop после обновления конфигурации.

Доступные инструменты

get_schedule

Получить школьное расписание на определённую дату.

Параметры:

• date_str (необязательно): Дата, на которую нужно получить расписание. По умолчанию — "сегодня".

  • Поддерживается: "today", "tomorrow", "yesterday"

  • Названия дней недели: "monday", "tuesday" и т.д. (английские или финские)

  • Форматы даты: "2024-03-15", "15.3.2024"

Пример: "Какое у меня расписание на понедельник?"

get_week_schedule

Получить расписание на полную неделю.

Параметры:

• start_date (необязательно): Дата начала недели. По умолчанию — сегодня.

Пример: "Покажи расписание на следующую неделю"

get_messages

Получить список сообщений из входящих. Каждое сообщение показывает индикатор прочитано/не прочитано (📖 прочитано, 📬 не прочитано).

Параметры:

• folder (необязательно): Имя папки — "inbox", "sent", "archive" или "drafts". По умолчанию — "inbox".

• limit (необязательно): Максимальное количество возвращаемых сообщений. По умолчанию — 20.

Для папок "sent" и "drafts" в списке отображается получатель ("Кому:") вместо отправителя.

Пример: "Проверь мои сообщения" / "Покажи мои отправленные сообщения"

get_message

Прочитать конкретное сообщение с полным содержимым. Примечание: просмотр сообщения автоматически помечает его как прочитанное на сервере Wilma.

Параметры:

• message_id: ID сообщения для чтения.

Пример: "Прочитай сообщение 12345"

set_message_read

Явно пометить сообщение как прочитанное. Полезно для отметки сообщений как прочитанных без чтения их полного содержимого. Wilma не поддерживает отметку сообщений как непрочитанных — это ограничение платформы.

Параметры:

• message_id: ID сообщения для отметки как прочитанного.

Пример: "Пометить сообщение 12345 как прочитанное"

get_recipients

Получить список доступных получателей сообщений (учителя, сотрудники, родители).

Параметры:

• query (необязательно): Фильтр имени без учёта регистра (например, фамилия учителя). Удобно, так как полный список получателей школы может быть длинным.

Каждый возвращённый получатель имеет строку id (например, r_guardian=11876_2893&n_class=33), которую можно напрямую передать в send_message.

Пример: "Кому я могу отправлять сообщения?" / "Найди получателя для г-на Смита"

send_message

Отправить новое сообщение любому получателю (учителю, сотруднику или родителю).

Параметры:

• recipient: Кому отправить — либо имя человека (например, "Galiana Fatima", автоматически разрешается по списку получателей), либо id получателя из get_recipients (например, "r_guardian=11876_2893&n_class=33"). Чтобы адресовать нескольким людям, объедините их id через &.

• subject: Тема сообщения

• body: Текст сообщения/содержимое

Если имя соответствует более чем одному человеку, инструмент возвращает список совпадений, чтобы вы могли выбрать конкретный id (он не будет угадывать).

Пример: "Отправь сообщение г-ну Смиту о домашнем задании"

Чтобы ответить на существующее сообщение, используйте reply_to_message — он автоматически определяет получателя из исходного сообщения.

reply_to_message

Ответить на существующее сообщение. Это предпочтительный способ ответа, так как он автоматически обрабатывает определение получателя через форму ответа Wilma, без необходимости искать ID получателей.

Параметры:

• message_id: ID сообщения, на которое нужно ответить (из get_messages)

• body: Текст ответного сообщения/содержимое

Пример: "Ответь на сообщение 12345, что я приду"

Примеры диалогов

После настройки вы можете спросить у Claude:

• "Какое у меня расписание на сегодня?"

• "Есть ли у меня занятия в пятницу?"

• "Покажи мои непрочитанные сообщения"

• "Прочитай сообщение от моего учителя"

• "Во сколько начинается школа завтра?"

Технические примечания

• У Wilma нет официального публичного API. Этот сервер использует обратный инжиниринг веб-интерфейса.

• Аутентификация использует сессионные cookie, полученные через процесс входа.

• Данные расписания извлекаются из встроенного JavaScript на странице расписания.

• Списки сообщений используют JSON-эндпоинты для каждой папки (/messages/list для входящих, /messages/list/outbox для отправленных, /messages/list/archive, /messages/list/drafts); отдельные сообщения требуют парсинга HTML.

• Отслеживание прочитано/не прочитано: JSON API Wilma включает поле Status для каждого сообщения — истинное значение означает не прочитано, ложное/отсутствие означает прочитано. Просмотр сообщения (GET-запрос) помечает его как прочитанное на стороне сервера. Нет API для отметки сообщения как непрочитанного.

• Отправка сообщений: Wilma не предоставляет получателей в виде элементов <option>. Средство выбора получателей (/messages/recipients) встраивает каждого доступного человека как .recipient-block, чья ссылка data-source кодирует селектор вида r_<type>=<id> (например, r_guardian, r_personnel, r_ownteachers). Для создания сообщения сервер выполняет GET-запрос к /messages/compose?<selector> (который возвращает форму с новым formkey и получателем, предварительно добавленным как скрытый ввод r_<type>), заполняет поля Subject и BodyText и отправляет POST-запрос с кнопкой addsavebtn "send". Вот почему новые сообщения теперь работают, а не только ответы.

• Сервер может потребовать обновлений, если веб-интерфейс Wilma изменится.

Разработка

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

# Run tests
pytest

Будущие возможности (планируется)

• Оценки и аттестации

• Записи об отсутствии/посещаемости

• Предстоящие экзамены

• Школьные новости/объявления

• Списки курсов

Лицензия

Лицензия MIT — см. файл LICENSE.

Отказ от ответственности

Это неофициальный проект, не связанный с Visma и не одобренный ею. Используйте на свой страх и риск. Соблюдайте условия использования Wilma и ограничения скорости.

Участие в разработке

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.