Wilma MCP 服务器

一个用于 Wilma（Visma 旗下的芬兰学校通信平台）的 MCP（模型上下文协议） 服务器。它允许 Claude 和其他兼容 MCP 的 AI 助手与学校数据进行交互，包括课程表、消息等。

功能

• 课程表 - 查看每日或每周的课程安排，包括科目、时间和教师

• 消息 - 阅读收件箱消息，显示已读/未读状态，查看完整内容，标记为已读

• 收件人 - 列出可用的消息收件人（教师、工作人员）

• 发送消息 - 编写并发送消息给教师

Related MCP server: Dnevnik.ru MCP Server

前提条件

• Python 3.11 或更高版本

• 一个 Wilma 账户（学生、家长或教师）

• 您学校的 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 .

配置

创建一个包含您的 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. 将 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”，列表显示的是收件人（“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。该服务器对 Web 界面进行了逆向工程。

• 身份验证使用通过登录流程获得的会话 cookie。

• 课程表数据从课程表页面中的嵌入式 JavaScript 中提取。

• 消息列表使用每个文件夹的 JSON 端点（收件箱使用 /messages/list，已发送使用 /messages/list/outbox，归档使用 /messages/list/archive，草稿使用 /messages/list/drafts）；单个消息需要 HTML 解析。

• 已读/未读跟踪：Wilma 的 JSON API 为每条消息包含一个 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 字段，然后使用 addsavebtn “发送”按钮进行 POST。这就是为什么新消息现在可以工作，而不仅仅是回复。

• 如果 Wilma 的 Web 界面发生变化，服务器可能需要更新。

开发

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

# Run tests
pytest

未来功能（计划中）

• 成绩和评估

• 缺勤/出勤记录

• 即将到来的考试

• 学校新闻/公告

• 课程列表

许可证

MIT 许可证 - 请参阅 LICENSE 文件。

免责声明

这是一个非官方项目，与 Visma 无关或未经其认可。使用风险自负。请尊重 Wilma 的服务条款和速率限制。

贡献

欢迎贡献！请随时提交拉取请求。