psquare

ParentSquare MCP 服务

重要

此存储库已归档。活跃开发已迁移至 thehesiod/psquare-mcp。

该项目以 parentsquare-mcp 的名称发布在 PyPI 上，并以 io.github.thehesiod/psquare 的名称发布在 MCP Registry 上。

旧名称 psquare-mcp / io.github.jasonko/psquare 已固定在 0.3.0 版本，不会再获得任何修复。迁移方法：pip uninstall psquare-mcp && pip install 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 端点）——这些 API 未公开发布，不保证稳定，且可能随时更改或被屏蔽，恕不另行通知。使用这些接口可能违反 ParentSquare 的服务条款；您有责任查阅服务条款，并自行判断您的使用是否可接受。

使用风险自负。 作者和贡献者不对使用本软件所产生的任何后果承担责任，包括但不限于：账户暂停或终止、数据丢失或损坏、错过通知或收到错误通知、多因素身份验证锁定、会话 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_links — 快速访问链接（Google Drive、外部网站）

学生

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

管理员（名册：学生和监护人）

读取工具始终可用；写入工具默认禁用，只有在设置 PS_ENABLE_WRITES 后才会运行（见下文）。每次写入都会记录到本地审计日志。v1 仅支持创建和编辑，不支持破坏性操作。

• list_students — 学校名册（id、姓名、年级、SIS id、监护人）的结构化 JSON 数据，可选择使用 grade / name_contains 进行筛选
• list_parents — 监护人名册（user_id、姓名、电子邮件、电话、关联学生）的结构化 JSON 数据，可选择使用 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 （写入） — 管理学生注册的班级。这些操作与班级教职员工写入共用同一个全局串行锁，因为更新学生所属班级可能会替换该学生的完整注册列表。

身份验证

• submit_mfa_code — 使用 6 位代码完成 MFA 验证
• 支持 MCP elicitation，用于内联 MFA 提示
• 会话 Cookie 持久化到 ~/.parentsquare_cookies.json
• 会话过期时，从环境变量、1Password 或 LastPass CLI 加载凭据

设置

启用管理员写入工具

管理员写入工具（add_student、edit_student、add_parent、edit_parent、 link_guardian_to_student）会修改学校的实时名册，因此默认关闭。要启用这些工具，请在 服务的环境中设置 PS_ENABLE_WRITES=1（或 true/yes/on），然后重启。每次写入尝试（包括被拦截的尝试） 都会以 JSONL 格式追加到 PS_AUDIT_LOG（默认为 ~/.parentsquare_audit.log）。读取 工具（list_students、list_parents、list_grades、get_student）始终可用。

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

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

前提条件

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

1. 环境变量 — 设置 PS_USERNAME 和 PS_PASSWORD
2. 通过 PS_CREDENTIAL_PROVIDER 选择的凭据管理器（默认为 1password）：
   • 1Password CLI（op）— 其中包含名为 “Parentsquare” 的条目，且该条目含有 username 和 password 字段
   • 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": ["--from", "parentsquare-mcp", "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": ["--from", "parentsquare-mcp", "parentsquare-mcp"],
      "env": {
        "PS_CREDENTIAL_PROVIDER": "lastpass",
        "PS_LASTPASS_ITEM": "parentsquare.com"
      }
    }
  }
}

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

工作原理

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

1. 获取 HTML 页面（通过 PSClient.get_page()）或 JSON（通过 PSClient.get_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 查看），PDF 附件则会通过 pymupdf 提取文本。get_staff_member 也会返回内嵌的个人资料照片。

群组使用 GraphQL 端点（/graphql），而非抓取 HTML。目录和员工详情使用内部 /api/v2/ JSON:API。

依赖项

软件包	用途	许可证
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.jasonko/psquare