psquare

ParentSquare MCP 服务

一个 MCP（Model Context Protocol） 服务，可让 Claude 访问 ParentSquare——一个家校沟通平台。由于 ParentSquare 没有公开 API，此服务会使用已保存的会话 Cookie 抓取网页界面。

涵盖家长/监护人体验（动态、帖子、日历、消息、目录、报名、表单、付款）以及学校管理人员名册管理——读取学生和监护人名册，创建/编辑学生和监护人，并发送注册邀请。管理人员写入工具默认关闭，由 PS_ENABLE_WRITES 控制，每次写入都会记录到本地审计日志。

可在 MCP Registry 中通过 io.github.thehesiod/psquare 获取，也可在 PyPI 中通过 parentsquare-mcp 获取。

免责声明

本项目与 ParentSquare, Inc. 无关联，也未获其认可或赞助。“ParentSquare”及所有相关名称、徽标和商标均为 ParentSquare, Inc. 的财产。

此服务会与 ParentSquare 的未公开内部 API通信（抓取网页 UI 并调用其非公开的 /api/v2/ JSON 端点）——这些接口并未发布，也不保证稳定，并且可能随时更改或被屏蔽，恕不另行通知。使用这些接口可能违反 ParentSquare 的服务条款；您有责任查阅服务条款，并自行判断您的使用是否可以接受。

**使用风险自负。**作者和贡献者不对使用本软件造成的任何后果承担责任，包括但不限于：账户暂停或终止、数据丢失或损坏、通知遗漏或错误、MFA 锁定、会话 Cookie 泄露、IP 屏蔽，以及任何其他直接或间接损害。不提供任何保证——完整的 MIT 无担保条款请参见 LICENSE。

如果 ParentSquare 发布官方 API，则应弃用本项目，改用官方 API。

功能

动态和帖子

• get_feeds — 浏览分页学校动态，包含标题、作者、摘要和附件名称
• get_post — 完整帖子详情，包含正文、评论、投票结果、报名项目，以及内嵌图像/PDF 内容（Claude 可以“看到”所附的日历、传单等）
• get_group_feed — 查看特定群组的帖子

日历

• get_calendar_events — 将 ICS 日历中的活动作为结构化 JSON 返回（标题、开始/结束时间、地点、描述）
• 如果 ICS 日历为空，则会引导 Claude 搜索动态帖子中的图像/PDF 日历

沟通

• list_conversations / get_conversation — 阅读消息对话串
• get_directory — 以结构化 JSON 返回教职员工目录（姓名、职位、电话、user_id）
• get_staff_member — 查看完整教职员工详情，包括电子邮件、办公时间和内嵌头像

媒体和文件

• list_photos — 查看带 URL 的照片库
• list_files — 查看文档文件
• download_file — 将任意附件下载到本地磁盘

参与

• list_signups — 查看报名和 RSVP 帖子及进度跟踪（例如“53/103 项目”）
• list_notices — 查看提醒和安全文档
• list_polls — 查看投票、票数和获胜选项
• list_forms — 查看许可单和可签署表单
• list_payments — 查看付款项目、价格和汇总统计
• list_volunteer_hours — 查看已记录的志愿服务时数及总计

群组与发现

• list_schools — 学校和学生的结构化 JSON 数据
• list_school_features — 每所学校提供的版块（从侧边栏解析）
• list_groups — 群组及其活跃帖子数量和描述
• list_group_members — 完整的群组名录，以结构化 JSON 呈现，并区分普通成员、访客、所有者和管理员
• list_links — 快捷链接（Google Drive、外部网站）

学生

• get_student_dashboard — 学校、年级、班级和教师的结构化 JSON 数据

管理员

读取工具始终可用；下方标记为 (写入) 的工具默认已禁用，只有在设置 PS_ENABLE_WRITES 后才会运行（参见启用管理员写入工具）。每次写入尝试都会记录到本地审计日志，包括被权限门禁拦截的尝试。没有任何工具会删除记录——可以创建和编辑学生、监护人、班级及教职员工，但绝不会删除；移除操作只会解除关联（教职员工分配、班级注册或群组成员关系），底层的人员、班级和群组仍会保留。删除操作有意留给 ParentSquare 网站处理。

名册：学生与监护人

• list_students — 学校名册，以结构化 JSON 呈现（id、姓名、年级、SIS id、监护人），可选使用 grade / name_contains 筛选
• list_parents — 监护人名册，以结构化 JSON 呈现（user_id、姓名、电子邮件、电话、关联的学生），可选使用 name_contains / student_name_contains 筛选；提供 edit_parent / link_guardian_to_student 所需的 user_id
• list_grades — 学校的年级及其 grade_id 值（添加/编辑时需要）
• get_student — 单个学生的管理员详细信息（姓名、年级、SIS id、关联的监护人、班级）
• add_student (写入) — 在某个年级创建学生
• edit_student (写入) — 更新学生的姓名、SIS id 或年级（未更改的字段会保留）
• add_parent (写入) — 创建与某个学生关联的监护人
• edit_parent (写入) — 更新监护人的姓名、电子邮件或电话（保留现有关联）
• link_guardian_to_student (写入) — 将现有监护人与另一名学生关联
• invite_parent (写入) — 向一名监护人发送或重新发送 ParentSquare 注册邀请
• bulk_invite_parents (写入) — 一次邀请多名监护人；自动跳过已注册的监护人

班级、教职员工与注册

• list_classes / get_class — 学校的班级，以及包含完整教职员工名单（教师、助教、班级家长）的某个班级
• add_class (写入) — 创建班级；新班级在调用 set_class_visibility 前默认处于隐藏状态
• edit_class (写入) — 重命名班级或更改其年级
• set_class_visibility (写入) — 显示或隐藏班级（由日期决定，默认为今天）
• list_staff — 以结构化 JSON 格式列出教职员工和管理员名单（user_id、姓名、电子邮件、电话、角色/职称），并支持可选的 name_contains 筛选条件；提供 edit_staff / add_class_staff 所需的 user_id
• add_staff (写入) — 添加教师、教职员工或管理员，也可选择将其分配到班级
• edit_staff (写入) — 更新教职员工的姓名、电子邮件、电话、职称或员工 ID（保留班级分配和 STAFF/ADMIN 访问权限；不允许修改监护人，请使用 edit_parent）
• add_class_staff / remove_class_staff (写入) — 为班级分配或取消分配教师、助教和班级家长。单个服务进程内的班级成员写入操作会串行执行；切勿并行发出这些操作，并在每次操作后通过重新读取来验证结果。
• list_class_students — 查看注册到某个班级的学生
• add_class_students / remove_class_students / move_student_to_class (写入) — 管理学生注册到哪些班级。这些操作与班级教职员工写入操作共用同一个全局串行锁，因为学生所属班级的更新可能会替换该学生的完整注册列表。

群组写入目前支持手动选择的（CsvGroup）群组，不支持基于规则的群组或所有权更改。它们与班级/注册写入共用锁，会验证完整的目录读取结果，并在每次写入后验证成员资格和已保存的选择。即使跨服务进程，也必须串行执行。Classroom 中的 Room Parent 角色与 Room Parents 群组成员资格彼此独立。

身份验证

• submit_mfa_code — 使用 6 位代码完成 MFA 验证
• 支持 MCP elicitation，可内联提示输入 MFA 代码（设置 PS_NO_ELICIT 可为无人值守调用方禁用此功能）
• 会话 Cookie 持久化到 ~/.parentsquare_cookies.json
• 会话过期时，从环境变量、1Password 或 LastPass CLI 加载凭据

设置

启用管理员写入工具

管理员写入工具——即 Admin 下所有标记为 (write) 的工具，涵盖学生／监护人名单、班级、教职员工、班级注册和群组——会修改学校的实时数据，因此默认关闭。要启用这些工具，请在服务的环境中设置 PS_ENABLE_WRITES=1（或 true/yes/on），然后重启。每次写入尝试（包括被阻止的尝试）都会以 JSONL 格式追加到 PS_AUDIT_LOG（默认值为 ~/.parentsquare_audit.log）。管理员读取工具不受影响。

ParentSquare 的表单端点会对每个已接受的 POST 返回相同的通用 200“reload”响应，有些静默失败也会返回此响应。为避免误报成功，创建／关联工具（add_student、add_parent、link_guardian_to_student）会在写入后回读权威状态，只有在确实找到新记录后才报告 ✅ Success (verified)。如果 POST 已被接受，但回读时找不到变更，这些工具会返回 ⚠️ 警告，说明变更可能未持久化；如果无法执行回读，则会报告写入已提交但未经验证。

回读结果也会优先于 5xx 响应。ParentSquare 会在事务提交后呈现错误页面，因此服务器错误可能会掩盖已成功写入的数据——add_student 在每次创建时都出现过这种情况，直到找到缺失的 student[section_ids][] 表单参数。将这些情况报告为失败会导致用户重试，而每次重试都会重复创建真实的学生记录，且没有 API 可删除记录。因此，如果写入返回 5xx，但回读时找到了记录，该工具会报告 ✅ Success (verified)，并注明不要重试。明确拒绝的情况（4xx，或包含 alert-danger 提示的 200）仍会一律报告为失败，无论回读结果如何。

前提条件

凭据可以通过以下两种方式之一提供（按以下顺序检查）：

1. 环境变量 — 设置 PS_USERNAME 和 PS_PASSWORD
2. 由 PS_CREDENTIAL_PROVIDER 选择的凭据管理器（默认值为 1password）：
   • 1Password CLI（op）——其中包含一个带有 username 和 password 字段的“Parentsquare”条目
   • LastPass CLI（lpass）——设置 PS_CREDENTIAL_PROVIDER=lastpass。先在终端中运行 lpass login <your-lastpass-email>（可能会提示进行 MFA 验证）。默认读取 parentsquare.com 条目，可通过 PS_LASTPASS_ITEM（精确的条目名称或条目 ID）覆盖。

在 Claude Code 中安装

claude mcp add --transport stdio parentsquare -- uvx --from "parentsquare-mcp @ git+https://github.com/thehesiod/psquare-mcp" parentsquare-mcp

要启用帖子附件的 PDF 文本提取功能（可选，采用 AGPL-3.0 许可）：

claude mcp add --transport stdio parentsquare -- uvx --from "parentsquare-mcp[pdf] @ git+https://github.com/thehesiod/psquare-mcp" parentsquare-mcp

就这样

无需进一步配置。首次使用时，服务会从 ParentSquare 自动发现你的学校、学生和用户 ID。身份验证会自动处理——会话过期时，服务会从环境变量（或 1Password CLI）加载凭据并重新进行身份验证（如有需要，也会进行 MFA 验证）。

要在 Claude Code 中使用环境变量，请在 MCP 配置中添加一个 env 块：

{
  "mcpServers": {
    "parentsquare": {
      "command": "uvx",
      "args": ["parentsquare-mcp"],
      "env": {
        "PS_USERNAME": "[email protected]",
        "PS_PASSWORD": "your-password"
      }
    }
  }
}

**安全提示：**环境变量会将你的密码以明文形式放在 MCP 配置文件中。如果你选择密码管理器正是为了避免这种情况，建议使用 1Password 或 LastPass CLI 方式。

要使用 LastPass CLI 而非 1Password，请先登录一次（lpass login <your-lastpass-email>），然后在 MCP 配置中设置凭据提供方：

{
  "mcpServers": {
    "parentsquare": {
      "command": "uvx",
      "args": ["parentsquare-mcp"],
      "env": {
        "PS_CREDENTIAL_PROVIDER": "lastpass",
        "PS_LASTPASS_ITEM": "parentsquare.com"
      }
    }
  }
}

PS_LASTPASS_ITEM 为可选项（默认值为 parentsquare.com）。

无人值守使用（PS_NO_ELICIT）

需要 MFA 时，服务器会通过 MCP elicitation 在行内提示输入验证码。 该提示会等待人工输入，因此无人值守的调用方（例如 claude.ai routine 或 计划任务）无人可答，工具调用只会一直阻塞，直到 elicitation 超时。

设置 PS_NO_ELICIT=1 可跳过提示。工具会立即返回“需要 MFA 验证” 消息，调用方可以通过其他渠道获取验证码（例如通过 Gmail 或 Microsoft 365 MCP）， 并将其传递给 submit_mfa_code：

{
  "mcpServers": {
    "parentsquare": {
      "command": "uvx",
      "args": ["parentsquare-mcp"],
      "env": {
        "PS_NO_ELICIT": "1"
      }
    }
  }
}

该检查基于是否存在：任何非空值都会禁用 elicitation，因此 PS_NO_ELICIT=0 和 PS_NO_ELICIT=false 也会禁用它。要重新启用行内 提示，请完全取消设置该变量。

工作原理

该服务器使用 requests + BeautifulSoup 抓取 ParentSquare 服务端渲染的 HTML 页面。每个工具都遵循以下模式：

1. 获取：通过 PSClient.get_page() 获取 HTML 页面，或通过 PSClient.get_json() 获取 JSON（会在会话过期时自动重新登录）
2. 解析：使用 parsers/ 中专用的解析器，将结构化数据提取到数据类中
3. 返回：结果以结构化 JSON 字典（用于数据查询工具）或 Markdown 文本（用于内容丰富的工具）形式返回

数据查询工具（list_schools、get_directory、get_calendar_events、get_student_dashboard、get_staff_member）会返回结构化 JSON，便于以编程方式访问。内容工具（get_post、get_feeds、get_conversation）会返回 Markdown。

首次使用时，服务器会自动从 ParentSquare 发现你的学校、学生和用户 ID（无需配置文件）。

对于 get_post，系统会下载图片附件并将其作为 MCP Image 对象返回（以便 Claude 查看），并通过 pymupdf 提取 PDF 附件中的文本。get_staff_member 也会返回内嵌的个人资料照片。

群组发现使用 GraphQL（/graphql）；群组成员关系使用 HTML 目录和 Rails 表单。学校目录和教职员工详情使用内部 /api/v2/ JSON:API。

依赖项

Package	Purpose	License
mcp	Model Context Protocol SDK	MIT
requests	HTTP 客户端	Apache 2.0
beautifulsoup4	HTML 解析	MIT
icalendar	ICS 日历解析	BSD
pymupdf	PDF 文本提取（可选）	AGPL-3.0

许可证

MIT — 参见 LICENSE。注意：可选依赖项 pymupdf 使用 AGPL-3.0 许可证。

mcp-name: io.github.thehesiod/psquare