Somtoday (unofficial)

somtoday-mcp

Somtoday の保護者ポータル向け読み取り専用の MCP サーバーです。Cursor や Claude Desktop などの AI アシスタントから、保護者アカウントを使ってお子様の時間割、宿題、成績を確認できます。

コンピューター上で stdio 経由でローカル実行されます。Somtoday 以外にデータが送信されることはありません。

免責事項。 これは非公式のコミュニティプロジェクトです。Somtoday または Topicus との提携、承認、支援は受けていません。公式の保護者ポータルが使用する、文書化されていない内部 Web API と連携して動作するため、予告なく動作しなくなったり、動作が変わったりする可能性があります。ご自身のアカウントでの使用を想定しており、データの読み取りのみを行います。また、いかなる保証もなく現状有姿で提供されます（LICENSE を参照）。ご自身の責任において、Somtoday の利用規約に従って使用してください。「Somtoday」と「Topicus」はそれぞれの所有者の商標であり、本ソフトウェアが連携するサービスを説明する目的でのみ使用しています。

機能

ツール	内容
whoami	学校の名称、リンクされているお子様とその数値 ID、および利用できるポータルのセクションを確認できます。
lessons	1 日分の時間割と、その日が休校日かどうかを確認できます。各授業には type（ROOSTERTOETS/EXAMEN＝テスト）と、休講の場合は uitgevallen が含まれます。同じ日付の宿題とテスト範囲は homework から確認できます。
homework	日付範囲内の各日の学習プラン項目（デフォルトは今日から 6 日後まで、最大 42 日）を日ごとにまとめて確認できます。説明、学習目標、所要時間の目安、テストの種類、添付ファイル（リンク）、外部リンク、提出期間と状況、完了チェックが含まれます。
grades	最新の成績（最大 30 件）と教科ごとの平均を確認できます。
assignments	提出課題をすべて確認できます。提出期間、状況（提出予定、未提出、確認待ち、承認済み）、期限超過フラグ、説明、添付ファイル、リンクが含まれます。status=open を指定すると、未提出の課題に絞り込めます。
assignment_detail	保護者ポータルに表示される課題の詳細を確認できます。指示、ファイル、リンク、提出期間、状況が含まれます。提出済みファイルと教師からの反応は、生徒本人のセッションでのみ確認できます。
study_material	教科ごとの学習教材を確認できます。日付別のプラン内の授業教材、フォルダー別の年度添付ファイル（ファイルリンク）、外部リンク、学習方法や出版社へのリンクが含まれます。引数なしでは教科の一覧を表示し、vak で教科を指定します。all=true を指定するとすべての教科を取得します。
schedule	日付範囲内（デフォルトは今日から 6 日後まで、最大 42 日）の時間割を確認できます。時刻、授業時限、教科、教室、教師、種類（テスト、試験、保護者会など）、授業のメモ、変更と休講、添付ファイル、休校日が含まれます。
grades_latest	最新の成績から順に、教科、欄、説明、評点、配点、テストの種類、期間、日付、備考、再試験の情報を確認できます。limit（デフォルトは 50、最大 1000）と、SE の成績を指定する dossier=examen を使用できます。
grades_overview	学年度全体の成績一覧を確認できます。すべての教科、期間ごとのすべての成績、通知表の成績、配点、備考が含まれます。schooljaar で過年度を指定できます。
subject_grades	1 教科のすべての情報を確認できます。配点と備考を含むすべての成績欄、欄の定義（未採点のものも含む）、総合テストの内訳、成績進捗用および試験用の成績一覧が含まれます。vak を指定しない場合は教科の一覧を表示します。
exam_grades	学校試験の成績一覧（PTA/SE）を確認できます。教科ごとの SE 平均、すべての SE 成績、今後のテスト、テストの種類ごとの平均が含まれます。
absence	学年度または成績評価期間の欠席と記録（欠席、遅刻、退室、宿題・教材の準備不足）を、件数と各記録、および有効な措置とともに確認できます。
messages	メッセージを読み取り専用で確認できます。最新の会話（件名、送信者、日付、未読状態、プレビュー。zoek/ongelezen で絞り込み）または conversatieId で指定したスレッド全体を表示します。既読にはなりません。
news	学校からのお知らせをテキスト形式で新しい順に確認でき、未読件数も表示されます。
announcements	ポータルに表示される Somtoday 全体のお知らせを確認できます。
children	リンクされているお子様のプロフィール、クラス、学校情報（担任、学年、コース）、現在の在籍状況、利用できるポータルのセクションを確認できます。
school_info	学校の連絡先情報と学校案内ページを確認できます。paginaId でページを開けます。
teachers	お子様が教わっている教科と、メッセージを送信できる教職員を確認できます。
signing_requests	電子署名の依頼を読み取り専用で確認できます（署名は行われません）。各項目には document: {tool: "signing_document", id, available} が含まれます。
signing_document	ポータルのダウンロードボタンと同様に、署名依頼 1 件の PDF（署名済みの場合は署名済みの PDF）を取得できます。document.id を指定します。抽出したテキストを返し、最大サイズは 10 MB です。ログイン トークンを使って取得するため、download_attachment 用の fileUrl ではありません。
parent_evening	保護者会の詳細（時間枠、教師）を確認できます。メッセージから招待を検索します（読み取り専用で、予約は行われません）。
consents	写真の使用など、ポータルで設定されている同意事項を確認できます（読み取り専用）。
download_attachment	fileUrl を使って添付ファイルを読み取ります。https は Somtoday がホストするもののみ（SOMTODAY_MCP_ATTACHMENT_HOSTS で追加可能）、最大 10 MB、トークンは送信しません。PDF/テキスト/HTML/CSV/JSON からテキストを取得します。
auth_status	セッションが保存されているか、保存場所、最後のトークン更新の結果を確認できます。トークンは返しません。

• lessons では省略可能な date（YYYY-MM-DD、Europe/Amsterdam）を指定でき、省略した場合は明日が指定されます。期間指定ツールでは date、または from／to を指定します。
• アカウントに複数の子どもが紐付けられている場合は、whoami で確認できる数値 ID の leerlingId を指定してください。
• assignments で status=open を指定すると、デジタル提出が不要な期限超過の項目（inleveringenVerwacht: 0、例：紙で提出済み）は非表示になり、件数は verborgenZonderInlevering に表示されます。表示するには includeNoHandIn=true を指定してください。
• assignments は、教科、トピック、提出期間、ステータスが同じなどの重複に近い項目（例：2 つのグループに公開された 1 つの課題）を 1 つの項目にまとめ、その他の ID を duplicaatToekenningIds に含めます。個別に表示するには dedupe=false を指定してください。
• アカウントでセクションが無効になっている場合、ツールはその旨を伝え、その部分の API は呼び出しません。

含まれないもの：メッセージの送信、欠席の連絡、保護者面談の枠の予約、申請への署名、提出物のアップロードなど、データを変更する操作。

読み取り専用とプライバシー

• ツールは GET リクエストのみを送信します。データの書き込み、提出、既読への変更は行いません。
• サーバーは Somtoday のログインサーバーと API サーバーとのみ通信します。
• テレメトリや分析機能はありません。
• パスワードを入力するのは、ブラウザーウィンドウで開く Somtoday のログインページだけです。ツール、CLI フラグ、環境変数、プロンプトからパスワードを求めることはありません。
• ツールがトークンを返すことはありません。

時間割、宿題、成績は、子どもに関する個人データです。出力はご自身のデバイスに保存し、使用するのは利用資格のあるアカウントに限り、共有または再公開しないでください。GDPR に基づき、エクスポートしたデータの取り扱いにはご自身が責任を負います。

インストール

Node.js 22 以降が必要です（download_attachment と signing_document で使用する PDF テキスト抽出機能は Node 20 では動作しません）。

npm で somtoday-mcp として公開されており、このリポジトリのリリースワークフローに由来するプロベナンスが付属しています。

npx -y somtoday-mcp            # start the MCP server (used by your MCP client)
npx -y somtoday-mcp login      # sign in, once, in a terminal

ログイン時には通常のブラウザーウィンドウが開きます。Google Chrome（または Microsoft Edge）がインストールされている場合は、そのブラウザーが使用され、削除される一時プロファイルが新規作成されます。これにより、Somtoday の Cloudflare による「Verify you are human」チェックをより確実に通過できます。Chrome／Edge がない場合に限り、Playwright に同梱された Chromium にフォールバックします。その場合は、次のコマンドを一度実行してインストールしてください。

npx playwright install chromium

ウィンドウは「自動テスト ソフトウェアによって制御されています」という表示なしで起動します。ブラウザーのそれ以外の設定は変更されません。

チェックアウトしたリポジトリから：

git clone https://github.com/barzoj/somtoday-mcp.git
cd somtoday-mcp
npm install
npm run build
npx playwright install chromium   # only needed without Chrome/Edge
node dist/cli.js login

MCP クライアントの設定

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "somtoday": {
      "command": "npx",
      "args": ["-y", "somtoday-mcp"]
    }
  }
}

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "somtoday": {
      "command": "npx",
      "args": ["-y", "somtoday-mcp"]
    }
  }
}

ローカルのチェックアウトから

{
  "mcpServers": {
    "somtoday": {
      "command": "node",
      "args": ["/absolute/path/to/somtoday-mcp/dist/cli.js"]
    }
  }
}

サインイン

MCP クライアント内ではなく、ターミナルでログインを実行してください。

npx -y somtoday-mcp login

1. 通常の Somtoday ログインページが、ブラウザーウィンドウ（インストール済みの Chrome または Edge、ない場合は Playwright Chromium）で開きます。公式アプリと同じ方法で、学校を検索してください。
2. 2 段階認証を含め、通常どおりサインインしてください。制限時間は 10 分です（Cloudflare のチェックと学校の検索も含みます）。
3. ウィンドウが閉じると、セッションがコンピューターに保存され、MCP サーバーから使用できるようになります。

学校のテナント UUID が分かっている場合は、npx -y somtoday-mcp login --school-uuid <uuid> を実行すると学校の検索を省略できます。

サインインする前、または保存済みのセッションが使えなくなった後にツールを呼び出すと、次のメッセージが返されます。

ターミナルで npx somtoday-mcp login を実行してください

その場合は、再度ログインを実行してください。Somtoday に接続できない場合、ツールはログインを求めるのではなく、その旨を伝えます。

コマンド

npx -y somtoday-mcp status           # where the session is stored, last renewal result (no tokens)
npx -y somtoday-mcp status --check   # also renews the token and calls the API once
npx -y somtoday-mcp logout           # delete the stored session from this computer

同じ診断情報は、MCP クライアントから auth_status ツールを通じて利用できます。

複数の MCP クライアント（たとえば、2つの Cursor ウィンドウ）で1つのセッションを共有できます。トークンの更新は設定ディレクトリ内のロックファイルで直列化され、更新のたびに保存されたセッションを読み直します。

技術的な詳細

• Somtoday のネイティブアプリの公開（シークレット不要）クライアント ID とリダイレクト URI を使用した、PKCE（S256）対応の OAuth 2.0 認可コードフローです。クライアントシークレットはなく、Somtoday Connect パートナー API も使用しません。
• ログインページはカスタムの somtoday:// URL にリダイレクトします。Playwright は、ブラウザーウィンドウ内でそのリクエストから認可コードを読み取ります。ローカルのウェブサーバーは起動しません。
• 有効期間の短いアクセストークンはメモリ内にのみ保持されます。
• 学校は Somtoday 独自のログインページで選択します。学校のテナントはトークンのレスポンス（somtoday_tenant）から取得し、whoami と status に表示されるラベルは orgname クレームから取得します（取得できない場合は、アカウントの学校データを使用します）。

セッションの保存場所

プラットフォーム	保存場所
macOS	ログインキーチェーン、サービス somtoday-mcp。書き込みのたびに読み戻して確認します。確認に失敗した場合、または SOMTODAY_MCP_DISABLE_KEYCHAIN=1 が設定されている場合は、下記のファイルを使用します
Linux / Windows	$XDG_CONFIG_HOME/somtoday-mcp/（既定値は ~/.config/somtoday-mcp/）内の、パーミッションが 0600 の session.json

サインアウトするには、npx -y somtoday-mcp logout を実行します。

環境変数

変数	効果
XDG_CONFIG_HOME	ファイルの代替保存先のベースディレクトリです（既定値は ~/.config）。
SOMTODAY_MCP_CONFIG_DIR	$XDG_CONFIG_HOME/somtoday-mcp の代わりにこのディレクトリを使用します。
SOMTODAY_MCP_DISABLE_KEYCHAIN	1 に設定すると macOS キーチェーンをスキップし、常にファイルを使用します。

ログは stderr に出力されます（stdout は MCP プロトコル用に確保されています）。トークンのような値はマスキングされます。

開発

npm install
npm run lint
npm run format:check
npm run typecheck
npm run build
npm test

テストでネットワークにアクセスすることはありません。fetch とキーチェーンはモックされ、Somtoday のホストへのリクエストは意図的に失敗します。テストデータとプライバシーに関するルールは CONTRIBUTING.md を、脆弱性の報告方法は SECURITY.md を参照してください。

ouder-portal.openapi.yaml は、このプロジェクトが依存する保護者ポータル API の部分を、ポータルで確認した内容に基づいて記述したものです。公式の仕様ではありません。

実アカウントを使った手動確認

CI の対象外です。HTTP ステータスコードのみ記録し、トークン、コード、名前、API レスポンスは決して貼り付けないでください。

1. node dist/cli.js login を実行してサインインを完了します。
2. MCP クライアントから whoami、lessons、homework、grades を呼び出します。
3. MCP サーバーを再起動してから、もう一度ツールを呼び出し、保存済みのセッションが読み込まれることを確認します。

ライセンス

MIT。Somtoday または Topicus とは提携していません。