Librus Synergia

Librus MCP サーバー

AI アシスタントがLibrus Synergiaの学校成績簿（成績、出欠、時間割、 宿題、カレンダー、お知らせ、メッセージ、形成的評価、年度ごとの 履歴、休校日、生徒情報）にアクセスできるMCP サーバーです。 独立した librus-python-apiを基盤としており、 複数のアカウントで同時にログインできます。

バージョン 2.0 では、以前のすべてのバージョンで使われていたlibrus-apixバックエンドを置き換えています。 1.x からアップグレードしますか？1.x からのアップグレードをご覧ください。

クイックスタート

以下のコマンドでは、ネイティブ API 1.7.1 を使用する2.4.1を指定しています。Librus Synergia の ログイン名とパスワードが必要です。対話型の二要素認証が必要なアカウントには対応していません。

実行方法を 1 つ選んでください。

方法	おすすめの用途	認証情報
お使いのコンピューターで実行	同じマシン上の Claude Code、Claude Desktop、Gemini CLI、Codex、OpenCode、Hermes	非公開のconfig.json、ログイン数に制限なし
デスクトップバンドル	MCP バンドルに対応するアプリでワンクリックインストール	アプリの設定フォーム、1 件のログイン
Docker でセルフホスト	HTTP 経由で接続する、別のマシン上のエージェント	非公開のconfig.jsonまたは環境変数、ログイン数に制限なし
MCP レジストリ	公式レジストリからサーバーをインストールするクライアント	クライアントの設定フォーム、1 件のログイン

いずれの方法でも、ご自身で管理するマシン上でサーバーが実行されます。接続先は Librus のみです。プライバシーをご覧ください。

お使いのコンピューターで実行

このリポジトリをクローンしたり、Python を自分でインストールしたりする必要はありません。 uvが Python 3.14 とサーバーを 自動的にダウンロードします。

1. uv をインストールします。 macOS または Linux では、ターミナルを開いて次を実行します。

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows では、PowerShell を開いて次を実行します。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

その後、AI アシスタントを閉じて、もう一度開いてください。

2. 非公開の設定ファイルを作成します。 ユーザーアカウント内の非公開フォルダーにconfig.jsonとして保存してください。 プロジェクトや同期対象のフォルダーは避け、ログイン名とパスワードを入力します。

{
  "accounts": [
    {"alias": "daughter", "username": "12345", "password": "YOUR_PASSWORD"}
  ]
}

aliasは、このログインについて問い合わせるときに使う短い名前です。ログインを追加する場合は、 それぞれに独自のエイリアスを設定し、accountsにオブジェクトを追加します。

{
  "accounts": [
    {"alias": "anna", "username": "12345", "password": "FIRST_PASSWORD"},
    {"alias": "jan", "username": "67890", "password": "SECOND_PASSWORD"}
  ]
}

推奨される保存場所：

• macOS：/Users/YOUR_NAME/.config/librus-mcp/config.json
• Linux：/home/YOUR_NAME/.config/librus-mcp/config.json
• Windows：C:\Users\YOUR_NAME\.config\librus-mcp\config.json

初回起動時に、サーバーはファイルのアクセス権を自分のユーザーのみに制限し（macOS/Linux）、 非公開の状態ディレクトリ（~/.librus-mcp）と、そこに永続キーを作成します。 ほかに設定することはありません。通知と添付ファイルのダウンロードはデフォルトで有効、 メッセージの送信は無効です。変更するには、たとえば次を追加します。

"features": {"notifications": true, "attachments": false, "send_message": true}

ログインが 1 件の場合は、ファイルを省略して、代わりに環境変数を設定できます。 LIBRUS_USERNAME、LIBRUS_PASSWORD、必要に応じてLIBRUS_ALIAS（デフォルトは librus）を使用します。設定フォームで情報を収集するインストーラーでは、これらを使用します。

3. アシスタントを接続します。 ファイルの絶対パスに置き換えてください。

Claude Code：

claude mcp add --scope user --transport stdio librus \
  -- uvx --python 3.14 librus-mcp==2.4.1 --config /absolute/path/to/config.json

Claude Desktop（Settings > Developer > Edit Config）：

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["--python", "3.14", "librus-mcp==2.4.1", "--config", "/absolute/path/to/config.json"]
    }
  }
}

Gemini CLI：

gemini mcp add --scope user --transport stdio \
  librus uvx --python 3.14 librus-mcp==2.4.1 --config /absolute/path/to/config.json

OpenAI Codex CLI：

codex mcp add librus \
  -- uvx --python 3.14 librus-mcp==2.4.1 --config /absolute/path/to/config.json

OpenCode：

opencode mcp add librus --global -- \
  uvx --python 3.14 librus-mcp==2.4.1 --config /absolute/path/to/config.json

Hermes Agent（~/.hermes/config.yaml）：

mcp_servers:
  librus:
    command: "uvx"
    args: ["--python", "3.14", "librus-mcp==2.4.1", "--config", "/absolute/path/to/config.json"]

Librus に接続せずに設定を確認します。

uvx --python 3.14 librus-mcp==2.4.1 --config /absolute/path/to/config.json --check-config

GUI アシスタントがuvxを見つけられない場合は、絶対パス（which uvxまたは where uvx）を指定してください。ファイルを変更した後は、アシスタントを再起動するか、接続し直してください。

デスクトップバンドル（プレビュー）

各リリースには、GitHub リリースに librus-mcp-2.4.1.mcpb が添付されています。Claude Desktop など、MCP バンドルに対応したアプリで開いてください。アプリは Librus のログイン名とパスワードを尋ね、設定に保存し、このリリースのテストで使用した Python 3.14 と正確なバージョンの依存関係をインストールします。このバンドルで扱えるログインは 1 つです。複数のログインを使う場合は、お使いのコンピューター上でをご覧ください。

Docker を使用したセルフホスト

ご自身の Docker ホストでサーバーを実行し、HTTP 経由で別のマシン上のエージェントに接続します。各リクエストにはベアラートークンが必要です。サーバー自体には TLS 機能がないため、TLS 対応のリバースプロキシまたは Tailscale や WireGuard などのプライベートネットワーク経由でのみ公開してください。パブリックネットワークや共有ネットワーク上にポートを公開しないでください。

1. プライベートフォルダーを準備します。Docker ホスト上に、設定ファイルとトークンを保存するフォルダーを作成します。ファイルはコンテナーを実行するユーザーが所有し、そのユーザーだけが読み取れるようにしてください。

mkdir -p ~/librus-mcp/data && cd ~/librus-mcp
# config.json: the same format as above, any number of logins
docker run --rm ghcr.io/krzysztofbury/librus-mcp:2.4.1 --generate-token > token
chmod 600 config.json token

2. 次の compose.yaml で起動します。1000:1000 を id -u と id -g の出力に置き換えてください。

services:
  librus-mcp:
    image: ghcr.io/krzysztofbury/librus-mcp:2.4.1
    command: ["--transport", "http", "--allowed-host", "librus-mcp.example.lan:*"]
    user: "1000:1000"
    environment:
      LIBRUS_CONFIG: /config/config.json
      LIBRUS_MCP_TOKEN_FILE: /config/token
    volumes:
      - ./config.json:/config/config.json:ro
      - ./token:/config/token:ro
      - ./data:/data
    ports:
      # Loopback for a reverse proxy on this host, or your VPN address instead.
      - "127.0.0.1:8000:8000"
    restart: unless-stopped

docker compose up -d
docker compose logs librus-mcp

エンドポイントは、プロキシの HTTPS アドレス、またはポート 8000 の VPN アドレスにある /mcp です。--allowed-host にはクライアントが使用するホスト名を指定します。NAME:* は、ポートの有無を問わず NAME を受け付けます。リバースプロキシは元の Host ヘッダーを転送する必要があります。Caddy と Traefik はデフォルトで転送しますが、nginx では proxy_set_header Host $host; が必要です。--allowed-host を指定しない場合、サーバーは Host ヘッダーのチェックが無効であることをログに記録し、トークンのみに依存します。イメージ内のサーバーは、コンテナーのすべてのインターフェースで待ち受けます。アクセスできるユーザーは ports: の行で決まります。./data にはプライベート状態、永続キー、ダウンロードが保存されるため、バックアップしてください。

3. エージェントを接続します。トークンをベアラーヘッダーとして指定します。Hermes Agent の場合：

mcp_servers:
  librus:
    url: "https://librus-mcp.example.lan/mcp"
    headers:
      Authorization: "Bearer YOUR_TOKEN"

ストリーミング可能な HTTP に対応した他のクライアントでも、同じ URL とヘッダーを使用します。

HTTP モードに関する注意事項：

• 1 つのトークンで、設定済みのすべてのログインにアクセスできます。信頼できるユーザーごとにデプロイを 1 つ用意し、トークンが漏えいした場合は交換してください。
• 各ログインの通知ポーリングは、1 つのエージェントに任せてください。通知の配信と確認は、単一のコンシューマーを想定して設計されています。
• download_attachment は、Docker ホスト上の ./data/downloads にファイルを保存します。リモートエージェントはそのパスを読み取れません。小さなファイル（最大 256 KiB）は、有効期間の短い MCP リソースとしても提供されます。
• send_message を有効にすると、トークンを持つ人は誰でも送信プレビューを確定できます。サーバーは起動時にこの点を警告します。
• user: の行がない場合、コンテナーは uid 10001 で実行されます。名前付きボリュームはそのまま使用できますが、設定ファイルとトークンファイルは uid 10001 が所有している必要があります。
• ファイルの代わりに、LIBRUS_ACCOUNTS（アカウントの JSON リスト）、1 つのログイン用の LIBRUS_USERNAME と LIBRUS_PASSWORD、および LIBRUS_MCP_TOKEN を環境変数として渡すこともできます。

同じイメージは、Docker ホスト上のクライアント向けに stdio 経由でも実行できます。 docker run -i --rm -v librus-mcp-data:/data -e LIBRUS_USERNAME -e LIBRUS_PASSWORD ghcr.io/krzysztofbury/librus-mcp:2.4.1。

MCP レジストリ

このサーバーは、公式 MCP レジストリに io.github.krzysztofbury/librus-mcp として登録されており、PyPI パッケージ、コンテナーイメージ、デスクトップバンドルが掲載されています。レジストリからインストールするクライアントは、LIBRUS_USERNAME と LIBRUS_PASSWORD、および任意で LIBRUS_ALIAS を尋ねます。

1.x からのアップグレード

アシスタントの設定でバージョンを librus-mcp==2.4.1 に変更し、その前に --python 3.14 を追加して、既存の --config ファイルをそのまま使用してください。初回起動時に 2.0 が古い設定を自動的に調整します。キーを作成し、共有されている 1.x フォルダーへのアクセスをユーザーのみに制限し、削除された行動メモ設定を無視して、 初回の確認時に 1.x の通知履歴を引き継ぎます。切り替える前に、同じフォルダーを使用する 1.x サーバープロセスを停止してください。

1.x と同様に、通知と添付ファイルはデフォルトで有効のままです。ツール名と 結果は意図的に変更されています（たとえば、list_students は list_accounts に、 student_alias は account_alias になりました）。アシスタントは新しいツール一覧を 自動的に読み取ります。カスタムスクリプトは移行ガイドに従って更新する必要があります。

ツールと安全性

デフォルトのカタログには、型付きツールが 31 個あります。

• アカウント／プロフィール：list_accounts、get_student_information。
• 成績：get_grades、get_final_grades、get_grades_window。
• 出欠：get_attendance、get_attendance_window、get_attendance_detail、 get_attendance_frequency、get_subject_frequency。
• 学校：get_timetable、get_announcements、get_agenda、get_agenda_detail、 get_homework、get_homework_detail、get_completed_lessons、 get_school_year_archive、get_class_free_days。
• コミュニケーション：get_messages、get_message_content、get_recipient_types、 get_recipient_choices、get_recipients、get_message_correspondents、 get_teacher_subjects、get_message_unread_counts。
• 通知：get_new_notifications、get_notification_status、 acknowledge_notifications（機能 notifications）。
• ファイル：download_attachment と実行時のみの添付ファイルリソース（機能 attachments）。

send_message 機能を有効にすると、preview_message、send_message、 get_send_outcome、get_send_history が追加され、ツールは合計 35 個になります。通知と添付ファイルを無効にすると、ツールは 27 個になります。

コレクションは limit と cursor を使ってページ分割されます。同じ生徒のログインであっても、 ログインごとに独立しています。デフォルトでは最新のメッセージ機能が使用されます。従来のメールボックスを使用するには、アカウントに "messaging_backend": "legacy" を設定してください。行動メモは引き続き利用できません。 観察カードは形成的評価の成績としてサポートされています。点数およびパーセンテージによる成績（「Oceny punktowe」）は point レコードであり、その生の値はカテゴリで指定された尺度上のスコアです。

2.1 の新機能

既存の 2.0 の設定、コンテキストキー、永続状態はそのまま使えます。ツールカタログを更新するには、アシスタントを再接続してください。サーバーは API 1.7.1 に固定されています。

• get_grades または get_grades_window を使って、形成的評価や観察カードを取得できます。items に record_type="formative" と assessment オブジェクトを指定できるようになりました。数値形式および記述形式の記録には formative_id が追加されます。一致する assessment.detail_id は、追加の評定ではなく、ミラーリングされた項目を識別します。独自のコンシューマーでは新しいバリアントと、2.4 以降の point に対応する必要があります。以前の評定カーソルは再起動してください。
• get_school_year_archive を使って過去の学年度を読み取れます（デフォルトの上限は 10 件です）。項目は型付きの年度に続いて実績が並びます。評点と未加工の行動記録セルは、学校が提供した意味を保持します。
• get_class_free_days を使って、日付と任意の授業時限の範囲を読み取れます。不透明な型 ID は休日名ではなく、授業時限の境界が欠けていても終日イベントを意味するわけではありません。
• 最新のアカウントでは、get_message_correspondents を使ってバインドされたフィルター参照を取得し、それを correspondent として get_messages に渡します。現在の受信トレイの概要では、unread_only=true もサポートされています。カーソルを使う場合は、クエリ値を繰り返し指定してください。
• 過年度のメッセージ概要には get_messages(archived=true) を使います。アーカイブのフィルターとアーカイブ本文の表示には対応していません。archiving_in_progress は情報提供のみを目的としており、一覧表示を妨げません。
• get_teacher_subjects は最新の教師 ID と教科を対応付けます。これらは送信先参照ではありません。get_message_unread_counts は、メッセージを開いたり MCP の通知配信を変更したりせずに、現在およびアーカイブのフォルダー別件数を返します。

新しいコレクション読み取りにはすべて上限があります。レスポンス全体の上限は引き続き 512 KiB です。上限を超えた結果は LIMIT エラーとなり、テキストが黙って切り捨てられることはありません。不明な形成的評価マークアップがある場合、評定の読み取り全体が失敗します。形成的評価の行は、選択した週や最終ログインの表示範囲外にある場合があります。日付範囲によるフィルターは明示的に指定でき、サポートされています。

受信メッセージを開くには allow_mark_read=true が必要です。Librus によってメッセージが既読になるためです。送信には、正確なプレビュー、別途の人間による承認、confirm=true が必要です。CLAIMED または UNKNOWN の送信を再試行しないでください。新しいカレンダー通知を取得するには allow_consume_events=true が必要です。通知バッチは配信後に必ず確認応答してください。学校のコンテンツは信頼できないデータであり、指示ではありません。

状態、永続キー、ダウンロードは、デフォルトで ~/.librus-mcp の下に保存されます（設定の state_dir と download_dir）。再インストール後も参照情報と通知履歴を保持するには、状態ディレクトリをバックアップしてください。ダウンロードしたファイルはサーバーを実行しているマシンに保存されます。

download_attachment では、メッセージから返された reference を attachment_ref.message に渡します。また、get_message_content の添付ファイルの identifier と archived の値を、それぞれ attachment_ref.identifier と attachment_ref.archived に渡します。archived はファイルの名前空間を示します。現在のメッセージのファイルがアーカイブに保存されている場合もあります。省略した場合は、メッセージ参照に従います。ダウンロードによってメッセージ本文が開かれることはありません。

プライバシー

サーバーは、あなたが管理するマシン（自分のコンピューターまたは自分の Docker ホスト）で動作し、Librus のみに接続します。テレメトリーはなく、作成者やその他の第三者にデータが送られることもありません。ツールの結果は、それらを要求した AI アシスタントに送られます。PRIVACY.md を参照してください。

開発

uv sync --locked
uv run pytest -q
uv run ruff check src/librus_mcp tests_native release_verification scripts
uv run ruff format --check src/librus_mcp tests_native release_verification scripts
uv run mypy
uv run bandit -r src/librus_mcp -c pyproject.toml -q

設定の優先順位と運用者向けコマンドについては MIGRATION_2_0.md、プロトコルのルールについては MCP_CONTRACT.md、検証の証拠については NATIVE_TEST_PLAN.md、所有権については SPEC.md を参照してください。

ライセンスと制限事項

2.x は MIT ライセンスです。LICENSE_REVIEW.md にソースおよび依存関係のレビュー内容を記載しています。依存関係にはそれぞれ独自のライセンス条件が適用されます。未出荷の 1.x の参照資料は legacy_reference/ にあり、引き続き GPL-3.0-only が適用されます。また、それ以前のリリースには元のライセンスが適用されます。

これは非公式の連携機能であり、Librus とは提携していません。上流の変更によって、サポート対象の機能が動作しなくなる場合があります。セキュリティ上の問題は、SECURITY.md の説明に従って非公開で報告してください。