psquare

ParentSquare MCP サーバー

ParentSquare は学校と保護者のコミュニケーションプラットフォームです。この 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 の利用規約に違反する可能性があります。利用規約を確認し、ご自身の利用が許容されるかを判断する責任はユーザーにあります。

自己責任でご利用ください。 作者およびコントリビューターは、このソフトウェアの使用によって生じるあらゆる結果について責任を負いません。これには、アカウントの一時停止または停止、データの損失または破損、通知の見落としや誤り、多要素認証によるロックアウト、セッション Cookie の漏えい、IP アドレスのブロック、その他の直接的または間接的な損害が含まれますが、これらに限定されません。保証はありません。保証免責条項の全文については LICENSE の MIT ライセンスをご覧ください。

ParentSquare が公式 API を公開した場合、このプロジェクトは非推奨とし、公式 API を優先してください。

機能

フィードと投稿

• get_feeds — タイトル、投稿者、概要、添付ファイル名を含む、ページ分割された学校のフィードを閲覧します
• get_post — 本文、コメント、投票結果、申し込み項目、インライン画像／PDF コンテンツを含む投稿の詳細を取得します（Claude は添付されたカレンダーやチラシなどを「見る」ことができます）
• get_group_feed — 特定のグループの投稿を取得します

カレンダー

• get_calendar_events — ICS カレンダーのイベントを構造化 JSON で取得します（タイトル、開始／終了日時、場所、説明）
• ICS にイベントがない場合は、フィード投稿から画像／PDF のカレンダーを検索するよう Claude に案内します

コミュニケーション

• list_conversations / get_conversation — メッセージのスレッドを読み込みます
• get_directory — 職員ディレクトリを構造化 JSON で取得します（氏名、役職、電話番号、user_id）
• get_staff_member — メールアドレス、勤務時間、インラインのプロフィール写真を含む職員の詳細を取得します

メディアとファイル

• list_photos — URL 付きの写真ギャラリーを取得します
• list_files — ドキュメントファイルを取得します
• download_file — 任意の添付ファイルをローカルディスクにダウンロードします

参加

• list_signups — 進捗状況（例：「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 で表示

管理

読み取りツールは常に利用できます。以下で (write) と表示されているツールはデフォルトで無効になっており、PS_ENABLE_WRITES が設定されている場合にのみ実行されます（管理者向け書き込みツールを有効にするを参照）。ゲートによってブロックされた場合も含め、書き込みの試行はすべてローカル監査ログに記録されます。レコードを削除するツールはありません — 生徒、保護者、クラス、スタッフは作成および編集できますが、削除はできません。また、何かを削除するツールは関係（スタッフの割り当て、クラスへの登録、グループのメンバーシップ）のリンクを解除するだけで、元の人物、クラス、グループはそのまま残ります。削除操作は意図的に ParentSquare のウェブサイトに委ねられています。

名簿：生徒と保護者

• 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 — 生徒1人分の管理者向け詳細情報（名前、学年、SIS id、関連付けられた保護者、クラス）
• add_student (write) — 学年を指定して生徒を作成
• edit_student (write) — 生徒の名前、SIS id、または学年を更新（変更しないフィールドは保持）
• add_parent (write) — 生徒に関連付けて保護者を作成
• edit_parent (write) — 保護者の名前、メールアドレス、または電話番号を更新（既存の関連付けは保持）
• link_guardian_to_student (write) — 既存の保護者を別の生徒にも関連付け
• invite_parent (write) — 保護者1人に ParentSquare の登録招待を送信（または再送信）
• bulk_invite_parents (write) — 複数の保護者を一括で招待。登録済みの保護者は自動的にスキップ

クラス、スタッフ、在籍状況

• list_classes / get_class — 学校のクラス一覧と、スタッフ全員（教師、アシスタント、クラスルームペアレント）の一覧を含むクラス情報
• add_class (書き込み) — クラスを作成します。新しいクラスは set_class_visibility を設定するまで非表示になります
• edit_class (書き込み) — クラス名または学年を変更します
• set_class_visibility (書き込み) — クラスを表示または非表示にします（日付に基づき、デフォルトは今日です）
• list_staff — スタッフおよび管理者の名簿（user_id、名前、メールアドレス、電話番号、役職／肩書）を構造化 JSON で取得します。任意の name_contains フィルターを指定できます。edit_staff / add_class_staff に必要な user_id を取得できます
• add_staff (書き込み) — 教師、スタッフ、または管理者を追加し、任意でクラスに割り当てます
• edit_staff (書き込み) — スタッフの名前、メールアドレス、電話番号、肩書、またはスタッフ ID を更新します（クラスへの割り当てと STAFF/ADMIN 権限は保持されます。保護者は対象外です。edit_parent を使用してください）
• add_class_staff / remove_class_staff (書き込み) — クラスの教師、アシスタント、クラスルームペアレントを割り当て、または割り当て解除します。セクションのメンバーシップへの書き込みは、1つのサーバープロセス内で直列化されます。並列で実行せず、新たに読み取って各結果を確認してください。
• list_class_students — クラスに在籍する生徒を取得します
• add_class_students / remove_class_students / move_student_to_class (書き込み) — 生徒がどのクラスに在籍するかを管理します。生徒のセクション更新によって在籍クラスの一覧全体が置き換えられる可能性があるため、これらの操作はクラススタッフへの書き込みと同じグローバル直列化ロックを共有します。

グループメンバーシップ

• add_group_members (書き込み) — 手動選択グループに既存のユーザーを追加します（group_id、user_ids）。保存済みのユーザー／生徒の選択、オーナー、管理者、既存のゲストを保持し、すでに参加しているユーザーはスキップします。アカウントの作成や新しいゲストの招待は行いません。
• remove_group_members (書き込み) — 通常メンバーまたはゲストメンバーを、1人につき1回の検証済み操作で明示的に削除します。対象が空の場合、オーナー／管理者の場合、生徒に基づくメンバーシップを持つグループの場合は拒否し、不在のユーザーはスキップします。結果が不確かな場合は停止し、それまでに確認済みの変更を報告します。

グループへの書き込みで現在サポートされているのは、手動選択グループ（CsvGroup）のみです。ルールベースのグループやオーナー権限の変更には対応していません。クラス／在籍状況の書き込みロックを共有し、ディレクトリ全体の読み取りが完了していることを検証してから、各書き込みの後にメンバーシップと保存済みの選択内容の両方を確認します。サーバープロセスをまたぐ場合も、直列に実行してください。Classroom の Room Parent の役割と、Room Parents グループへのメンバーシップは独立しています。

認証

• submit_mfa_code — 6桁のコードで MFA 認証を完了します
• インライン MFA プロンプト用の MCP エリシテーションに対応しています（無人で実行する呼び出し元では PS_NO_ELICIT を設定して無効にしてください）
• セッション Cookie は ~/.parentsquare_cookies.json に保存されます
• セッションの有効期限が切れると、環境変数、1Password、または LastPass CLI から認証情報を読み込みます

セットアップ

管理者向け書き込みツールを有効にする

Admin の下にある (write) のマークが付いたすべてのツール（生徒・保護者の名簿、クラス、スタッフ、クラスへの登録、グループを対象とする管理者向け書き込みツール）は、学校の稼働中のデータを変更するため、デフォルトでは無効になっています。有効にするには、サーバーの環境変数に PS_ENABLE_WRITES=1（または true／yes／on）を設定して、再起動してください。書き込みの試行はすべて（ブロックされたものも含め）、PS_AUDIT_LOG（デフォルトは ~/.parentsquare_audit.log）に JSONL 形式で追記されます。管理者向け読み取りツールは、常に使用できます。

ParentSquare のフォームエンドポイントは、受け付けたすべての POST に対して、同じ汎用の 200「reload」レスポンスを返します。書き込みが失敗しても何も通知されない場合にも、このレスポンスが返ることがあります。誤って成功と判定しないよう、作成・リンクツール（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）— 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 CLI または LastPass CLI の使用をお勧めします。

1Password の代わりに LastPass CLI を使用するには、1 回ログインし（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 のルーチンや スケジュール済みジョブなど、無人で実行する呼び出し元は応答できず、ツール呼び出しは elicitation がタイムアウトするまでブロックされます。

PS_NO_ELICIT=1 を設定すると、プロンプトをスキップできます。ツールは「MFA verification required」というメッセージをすぐに返し、呼び出し元は別経路（たとえば 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 でも無効になります。インラインのプロンプトを再度有効にするには、変数を完全に unset してください。

動作の仕組み

サーバーは requests と BeautifulSoup を使って、ParentSquare のサーバー側でレンダリングされた HTML ページをスクレイピングします。各ツールは次のパターンに従います。

1. 取得：PSClient.get_page() で HTML ページを、または PSClient.get_json() で JSON を取得します（セッションの期限切れ時には自動で再ログインします）
2. 解析：parsers/ 内の専用パーサーで解析し、構造化データをデータクラスに抽出します
3. 返却：構造化 JSON dict（データ検索ツールの場合）または 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 ディレクトリと Rails フォームを使用します。学校のディレクトリとスタッフの詳細には、内部の /api/v2/ JSON:API を使用します。

依存関係

Package	Purpose	License
mcp	Model Context Protocol SDK	MIT
requests	HTTP client	Apache 2.0
beautifulsoup4	HTML parsing	MIT
icalendar	ICS calendar parsing	BSD
pymupdf	PDF text extraction (optional)	AGPL-3.0

ライセンス

MIT — LICENSE を参照してください。注：オプションの依存関係である pymupdf は AGPL-3.0 ライセンスです。

mcp-name: io.github.thehesiod/psquare