Wilma MCP Server

MCP (Model Context Protocol) 서버로, Visma의 핀란드 학교 커뮤니케이션 플랫폼인 Wilma를 위한 것입니다. 이를 통해 Claude 및 기타 MCP 호환 AI 어시스턴트가 시간표, 메시지 등을 포함한 학교 데이터와 상호작용할 수 있습니다.

기능

• 시간표 - 과목, 시간, 교사가 포함된 일일 또는 주간 시간표 보기

• 메시지 - 읽음/안 읽음 상태로 받은 편지함 메시지 읽기, 전체 내용 보기, 읽음 표시하기

• 수신자 - 메시지를 보낼 수 있는 수신자(교사, 교직원) 목록 보기

• 메시지 보내기 - 교사에게 메시지 작성 및 보내기

Related MCP server: Dnevnik.ru MCP Server

사전 요구 사항

• Python 3.11 이상

• Wilma 계정(학생, 보호자 또는 교사)

• 학교의 Wilma URL (예: 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 .

구성

Wilma 자격 증명이 담긴 .env 파일을 만드세요:

cp .env.example .env

.env 파일을 편집하세요:

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

보안 참고: .env 파일을 버전 관리에 커밋하지 마세요.

OpenClaw와 함께 사용하기

OpenClaw를 사용한다면, 이 프로젝트에는 에이전트가 Wilma MCP 도구를 사용하는 방법을 자동으로 알려주는 SKILL.md가 포함되어 있습니다.

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"입니다.

  • 지원: "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"의 경우 목록에는 보낸 사람 대신 수신자("To:")가 표시됩니다.

예시: "내 메시지 확인해 줘" / "내가 보낸 메시지 보여줘"

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에 직접 전달할 수 있습니다.

예시: "누구에게 메시지를 보낼 수 있지?" / "Smith 선생님의 수신자를 찾아 줘"

send_message

모든 수신자(교사, 교직원 또는 보호자)에게 새 메시지를 보냅니다.

매개변수:

• recipient: 보낼 대상 — 사람의 이름(예: "Galiana Fatima", 수신자 목록에서 자동으로 확인됨) 또는 get_recipients의 수신자 id(예: "r_guardian=11876_2893&n_class=33"). 여러 사람에게 보내려면 id를 &로 연결하세요.

• subject: 메시지 제목

• body: 메시지 본문/내용

이름이 여러 사람과 일치하면 도구는 일치하는 목록을 반환하므로 특정 id를 선택할 수 있습니다(추측하지 않습니다).

예시: "Smith 선생님에게 숙제에 관한 메시지를 보내 줘"

기존 메시지에 회신하려면 reply_to_message를 대신 사용하세요 — 원본 메시지에서 수신자를 자동으로 확인합니다.

reply_to_message

기존 메시지에 회신합니다. Wilma의 회신 양식을 통해 수신자 확인을 자동으로 처리하므로 수신자 ID를 조회할 필요 없이 회신하는 권장 방법입니다.

매개변수:

• message_id: 회신할 메시지의 ID (get_messages에서 가져옴)

• body: 회신 메시지 본문/내용

예시: "메시지 12345에 참석하겠다고 회신해 줘"

대화 예시

구성이 완료되면 Claude에게 다음과 같이 물어볼 수 있습니다:

• "오늘 시간표가 뭐야?"

• "금요일에 수업 있어?"

• "안 읽은 메시지 보여줘"

• "선생님에게 온 메시지 읽어 줘"

• "내일 학교 몇 시에 시작해?"

기술 참고 사항

• Wilma에는 공식 공개 API가 없습니다. 이 서버는 웹 인터페이스를 리버스 엔지니어링합니다.

• 인증은 로그인 흐름을 통해 얻은 세션 쿠키를 사용합니다.

• 시간표 데이터는 시간표 페이지에 포함된 JavaScript에서 추출됩니다.

• 메시지 목록은 폴더별 JSON 엔드포인트를 사용합니다 (받은 편지함의 경우 /messages/list, 보낸 편지함의 경우 /messages/list/outbox, /messages/list/archive, /messages/list/drafts); 개별 메시지는 HTML 파싱이 필요합니다.

• 읽음/안 읽음 추적: Wilma의 JSON API에는 메시지별로 Status 필드가 있습니다 — truthy는 안 읽음, falsy/부재는 읽음을 의미합니다. 메시지를 열람하면 (GET 요청) 서버 측에서 읽음으로 표시됩니다. 메시지를 안 읽음으로 표시하는 API는 없습니다.

• 메시지 보내기: Wilma는 수신자를 <option> 요소로 노출하지 않습니다. 수신자 선택기(/messages/recipients)는 각 연락 가능한 사람을 .recipient-block으로 포함하며, 그 data-source 링크는 r_<type>=<id> 형식의 선택자를 인코딩합니다 (예: r_guardian, r_personnel, r_ownteachers). 메시지를 작성하기 위해 서버는 /messages/compose?<selector>를 GET합니다 (새로운 formkey가 있는 양식과 수신자가 숨겨진 r_<type> 입력으로 미리 추가된 상태를 반환합니다). 그런 다음 Subject 및 BodyText 필드를 채우고 addsavebtn "보내기" 버튼으로 POST합니다. 이것이 회신뿐만 아니라 새 메시지도 이제 작동하는 이유입니다.

• Wilma의 웹 인터페이스가 변경되면 서버 업데이트가 필요할 수 있습니다.

개발

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

# Run tests
pytest

향후 기능 (계획)

• 성적 및 평가

• 결석/출석 기록

• 다가오는 시험

• 학교 소식/공지

• 강좌 목록

라이선스

MIT 라이선스 - LICENSE 파일을 참조하세요.

고지 사항

이 프로젝트는 비공식 프로젝트이며 Visma와 제휴하거나 보증하지 않습니다. 사용에 따른 책임은 본인에게 있습니다. Wilma의 서비스 약관과 요청 속도 제한을 준수하시기 바랍니다.

기여

기여를 환영합니다! 언제든지 Pull Request를 제출해 주세요.