psquare

ParentSquare MCP サーバー

重要

このリポジトリはアーカイブされています。現在の開発は thehesiod/psquare-mcp に移行しています。

PyPI では parentsquare-mcp、 MCP Registry では io.github.thehesiod/psquare として公開されています。

古い psquare-mcp／io.github.jasonko/psquare の名前は 0.3.0 で固定され、今後修正は行われません。移行するには、次のコマンドを実行してください：pip uninstall psquare-mcp && pip install parentsquare-mcp （コマンド名とインポート名に変更はありません）。

Claude が、学校と保護者のコミュニケーションプラットフォームである ParentSquare にアクセスできるようにする、MCP（Model Context Protocol） サーバーです。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 にイベントがない場合は、フィード投稿から画像／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_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 — 生徒 1 人の管理者向け詳細情報（名前、学年、SIS id、紐付けられた保護者、クラス）
• add_student (書き込み) — 学年に生徒を追加
• edit_student (書き込み) — 生徒の名前、SIS id、学年を更新（変更しないフィールドは保持）
• add_parent (書き込み) — 生徒に紐付けた保護者を作成
• edit_parent (書き込み) — 保護者の名前、メールアドレス、電話番号を更新（既存の紐付けは保持）
• link_guardian_to_student (書き込み) — 既存の保護者を別の生徒にも紐付け
• invite_parent (書き込み) — 保護者 1 人に 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 (書き込み) — クラスの教師、アシスタント、クラス保護者を割り当てたり、割り当てを解除したりします。セクションメンバーシップへの書き込みは、1 つのサーバープロセス内で直列化されます。並列で実行せず、毎回、新たに読み取って結果を確認してください。
• list_class_students — クラスに在籍する生徒
• add_class_students / remove_class_students / move_student_to_class (書き込み) — 生徒がどのクラスに在籍するかを管理します。生徒のセクション更新によって在籍クラスのリスト全体が置き換えられる場合があるため、これらのツールはクラス職員の書き込みと同じグローバルな直列化ロックを共有します。

認証

• submit_mfa_code — 6 桁のコードで MFA 認証を完了します
• MCP エリシテーションによるインライン 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）を設定して、再起動してください。すべての書き込み試行（ブロックされたものも含む）は、 PS_AUDIT_LOG（デフォルトは ~/.parentsquare_audit.log）に JSONL 形式で追記されます。読み取り ツール（list_students、list_parents、list_grades、get_student）は常に使用できます。

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": ["--from", "parentsquare-mcp", "parentsquare-mcp"],
      "env": {
        "PS_USERNAME": "[email protected]",
        "PS_PASSWORD": "your-password"
      }
    }
  }
}

セキュリティに関する注意： 環境変数を使用すると、MCP 設定ファイル内にパスワードが平文で保存されます。それを避けるためにパスワードマネージャーを選んだ場合は、1Password または LastPass CLI を使用してください。

1Password の代わりに LastPass CLI を使用するには、一度ログイン（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. 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 が画像を確認できます。また、PDF の添付ファイルは pymupdf を使用してテキストが抽出されます。get_staff_member も、プロフィール写真をインラインで返します。

グループには HTML スクレイピングではなく、GraphQL エンドポイント（/graphql）を使用します。ディレクトリとスタッフの詳細には、内部の /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