Servidor MCP para Wilma

Un servidor MCP (Model Context Protocol) para Wilma – la plataforma de comunicación escolar finlandesa de Visma. Permite que Claude y otros asistentes de IA compatibles con MCP interactúen con datos escolares como horarios, mensajes y más.

Funcionalidades

• Horario – Consulta horarios diarios o semanales con asignaturas, horarios y profesores

• Mensajes – Lee mensajes de la bandeja de entrada con estado leído/no leído, visualiza el contenido completo, marca como leídos

• Destinatarios – Lista los destinatarios de mensajes disponibles (profesores, personal)

• Enviar mensajes – Redacta y envía mensajes a profesores

Related MCP server: Dnevnik.ru MCP Server

Requisitos previos

• Python 3.11 o superior

• Una cuenta de Wilma (estudiante, tutor o profesor)

• La URL de Wilma de tu escuela (p. ej., https://yourschool.inschool.fi)

Instalación

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

Configuración

Crea un archivo .env con tus credenciales de Wilma:

cp .env.example .env

Edita .env:

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

Nota de seguridad: Nunca subas tu archivo .env al control de versiones.

Uso con OpenClaw

Si usas OpenClaw, este proyecto incluye un SKILL.md que enseña automáticamente a tu agente cómo usar las herramientas MCP de Wilma.

1. Completa los pasos de Instalación y Configuración anteriores.

2. Añade el servidor MCP a la configuración de tu Claude Code (~/.claude.json o .mcp.json del proyecto):

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

3. Coloca o enlaza simbólicamente el SKILL.md en tu directorio de habilidades de OpenClaw para que el agente pueda descubrirlo.

Uso con Claude Desktop

Añade el servidor al archivo de configuración de 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"
    }
  }
}

Reinicia Claude Desktop después de actualizar la configuración.

Herramientas disponibles

get_schedule

Obtén el horario escolar para una fecha concreta.

Parámetros:

• date_str (opcional): Fecha para la que obtener el horario. Por defecto es "today".

  • Admite: "today", "tomorrow", "yesterday"

  • Nombres de días de la semana: "monday", "tuesday", etc. (inglés o finés)

  • Formatos de fecha: "2024-03-15", "15.3.2024"

Ejemplo: "¿Cuál es mi horario para el lunes?"

get_week_schedule

Obtén el horario de una semana completa.

Parámetros:

• start_date (opcional): Fecha de inicio de la semana. Por defecto es hoy.

Ejemplo: "Muéstrame el horario de la próxima semana"

get_messages

Obtén la lista de mensajes de la bandeja de entrada. Cada mensaje muestra un indicador de leído/no leído (📖 leído, 📬 no leído).

Parámetros:

• folder (opcional): Nombre de la carpeta – "inbox", "sent", "archive" o "drafts". Por defecto es "inbox".

• limit (opcional): Número máximo de mensajes a devolver. Por defecto es 20.

Para "sent" y "drafts", el listado muestra el destinatario ("Para:") en lugar del remitente.

Ejemplo: "Revisa mis mensajes" / "Muestra mis mensajes enviados"

get_message

Lee un mensaje específico con su contenido completo. Nota: visualizar un mensaje lo marca automáticamente como leído en el servidor de Wilma.

Parámetros:

• message_id: El ID del mensaje a leer.

Ejemplo: "Lee el mensaje 12345"

set_message_read

Marca explícitamente un mensaje como leído. Útil para marcar mensajes como leídos sin leer su contenido completo. Wilma no permite marcar mensajes como no leídos; es una limitación de la plataforma.

Parámetros:

• message_id: El ID del mensaje a marcar como leído.

Ejemplo: "Marca el mensaje 12345 como leído"

get_recipients

Obtén la lista de destinatarios de mensajes disponibles (profesores, personal, tutores).

Parámetros:

• query (opcional): Filtro de nombre que no distingue mayúsculas/minúsculas (p. ej., el apellido de un profesor). Útil porque la lista completa de destinatarios de una escuela puede ser larga.

Cada destinatario devuelto tiene una cadena id (p. ej., r_guardian=11876_2893&n_class=33) que puedes pasar directamente a send_message.

Ejemplo: "¿A quién puedo enviar mensajes?" / "Busca el destinatario para el Sr. Smith"

send_message

Envía un nuevo mensaje a cualquier destinatario (profesor, miembro del personal o tutor).

Parámetros:

• recipient: A quién enviarlo – ya sea el nombre de una persona (p. ej., "Galiana Fatima", resuelto automáticamente contra la lista de destinatarios) o un id de destinatario de get_recipients (p. ej., "r_guardian=11876_2893&n_class=33"). Para dirigirse a varias personas, une sus ids con &.

• subject: Asunto del mensaje

• body: Cuerpo/contenido del mensaje

Si un nombre coincide con más de una persona, la herramienta devuelve la lista de coincidencias para que puedas elegir un id específico (no adivinará).

Ejemplo: "Envía un mensaje al Sr. Smith sobre los deberes"

Para responder a un mensaje existente, usa reply_to_message en su lugar: resuelve el destinatario automáticamente a partir del mensaje original.

reply_to_message

Responde a un mensaje existente. Esta es la forma preferida de responder, ya que gestiona la resolución del destinatario automáticamente a través del formulario de respuesta de Wilma, sin necesidad de buscar IDs de destinatarios.

Parámetros:

• message_id: ID del mensaje al que responder (de get_messages)

• body: Cuerpo/contenido del mensaje de respuesta

Ejemplo: "Responde al mensaje 12345 diciendo que asistiré"

Conversaciones de ejemplo

Una vez configurado, puedes preguntar a Claude:

• "¿Cuál es mi horario de hoy?"

• "¿Tengo clases el viernes?"

• "Muéstrame mis mensajes no leídos"

• "Lee el mensaje de mi profesor"

• "¿A qué hora empieza la escuela mañana?"

Notas técnicas

• Wilma no tiene una API pública oficial. Este servidor realiza ingeniería inversa de la interfaz web.

• La autenticación utiliza cookies de sesión obtenidas mediante el flujo de inicio de sesión.

• Los datos del horario se extraen de JavaScript incrustado en la página del horario.

• Las listas de mensajes usan endpoints JSON por carpeta (/messages/list para la bandeja de entrada, /messages/list/outbox para enviados, /messages/list/archive, /messages/list/drafts); los mensajes individuales requieren análisis HTML.

• Seguimiento de leído/no leído: La API JSON de Wilma incluye un campo Status por mensaje – verdadero significa no leído, falso/ausente significa leído. Visualizar un mensaje (solicitud GET) lo marca como leído en el servidor. No hay API para marcar un mensaje como no leído.

• Envío de mensajes: Wilma no expone destinatarios como elementos <option>. El selector de destinatarios (/messages/recipients) incrusta cada persona contactable como un .recipient-block cuyo enlace data-source codifica un selector de la forma r_<type>=<id> (p. ej., r_guardian, r_personnel, r_ownteachers). Para redactar, el servidor hace GET a /messages/compose?<selector> (que devuelve el formulario con una formkey nueva y el destinatario ya añadido como una entrada oculta r_<type>), rellena los campos Subject y BodyText, y hace POST con el botón addsavebtn de "send". Por eso ahora funcionan los mensajes nuevos, no solo las respuestas.

• Es posible que el servidor necesite actualizaciones si la interfaz web de Wilma cambia.

Desarrollo

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

# Run tests
pytest

Funcionalidades futuras (planificadas)

• Calificaciones y evaluaciones

• Registros de ausencia/asistencia

• Exámenes próximos

• Noticias/anuncios escolares

• Listados de cursos

Licencia

Licencia MIT – consulta el archivo LICENSE.

Aviso legal

Este es un proyecto no oficial y no está afiliado ni respaldado por Visma. Úsalo bajo tu propio riesgo. Respeta los términos de servicio y los límites de tasa de Wilma.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Pull Request.