Wilma MCP Server

Wilma（Visma が提供するフィンランドの学校向けコミュニケーションプラットフォーム）向けの MCP（Model Context Protocol） サーバーです。これにより、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 を使用している場合、このプロジェクトには SKILL.md が含まれており、エージェントが Wilma MCP ツールの使い方を自動的に学習します。

1. 上記のインストールと設定の手順を完了します。

2. Claude Code の設定（~/.claude.json またはプロジェクトの .mcp.json）に MCP サーバーを追加します。

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

1週間分のスケジュールを取得します。

パラメーター:

• start_date（オプション）: 週の開始日。デフォルトは今日。

例: 「来週のスケジュールを見せて」

get_messages

受信箱からメッセージのリストを取得します。各メッセージには既読/未読インジケーター（📖 既読、📬 未読）が表示されます。

パラメーター:

• folder（オプション）: フォルダ名 - "inbox"、"sent"、"archive"、"drafts"。デフォルトは "inbox"。

• limit（オプション）: 返す最大メッセージ数。デフォルトは 20。

「送信済み」と「下書き」の場合、送信者ではなく受信者（「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 に直接渡すことができます。

例: 「誰にメッセージを送れますか？」/「スミス先生の受信者を探して」

send_message

任意の受信者（教師、スタッフ、保護者）に新しいメッセージを送信します。

パラメーター:

• recipient: 送信先。人物の名前（例："Galiana Fatima"、受信者リストから自動解決）または get_recipients からの受信者 id（例："r_guardian=11876_2893&n_class=33"）。複数の人に送信するには、id を & で結合します。

• subject: メッセージの件名

• body: メッセージ本文/内容

名前が複数の人物と一致する場合、ツールは一致したリストを返すため、特定の id を選択できます（推測は行いません）。

例: 「スミス先生に宿題についてメッセージを送って」

既存のメッセージに返信するには、代わりに reply_to_message を使用してください。元のメッセージから自動的に受信者を解決します。

reply_to_message

既存のメッセージに返信します。受信者 ID を調べる必要がなく、Wilma の返信フォームを介して自動的に受信者を解決するため、これが推奨される返信方法です。

パラメーター:

• message_id: 返信するメッセージの ID（get_messages から）

• body: 返信メッセージの本文/内容

例: 「メッセージ 12345 に出席すると返信して」

会話例

設定が完了すると、Claude に次のように質問できます。

• 「今日のスケジュールは？」

• 「金曜日に授業はありますか？」

• 「未読メッセージを見せて」

• 「先生からのメッセージを読んで」

• 「明日の学校の開始時間は？」

技術的な注意事項

• Wilma には公式の公開 API はありません。このサーバーは Web インターフェースをリバースエンジニアリングしています。

• 認証には、ログインフローを介して取得したセッション Cookie を使用します。

• スケジュールデータは、スケジュールページの埋め込み 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 の Web インターフェースが変更された場合、サーバーの更新が必要になる可能性があります。

開発

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

# Run tests
pytest

将来の機能（計画中）

• 成績と評価

• 欠席/出席記録

• 今後の試験

• 学校のニュース/お知らせ

• コース一覧

ライセンス

MIT ライセンス - LICENSE ファイルを参照してください。

免責事項

これは非公式のプロジェクトであり、Visma とは提携または承認されていません。自己責任で使用してください。Wilma の利用規約とレート制限を尊重してください。

貢献

貢献は歓迎します！プルリクエストを送信してください。