BIT101 MCP

北京理工大学の学生向けのローカル・読み取り専用 Model Context Protocol（MCP） サービスです。BIT101 コミュニティのコンテンツ、授業評価、個人の時間割、成績、楽学カレンダーを、Agent が理解しやすい構造化データに変換し、自然言語で直接質問できるようにします。

[!IMPORTANT] 本プロジェクトは非公式のコミュニティプロジェクトであり、北京理工大学および BIT101 公式とは一切関係ありません。Windows では主要フローの実機テストが完了しており、Fedora 43 + niri での動作も確認済みです。プロジェクトは依然として MVP 段階にあります。使用前に認証・セキュリティ・プライバシーをお読みください。

できること

• 今日の BIT101 投稿を要約する、またはキーワードで過去の議論を検索する

• 授業、教員、過去の学生評価を照会する

• 今日、今週、来週、または指定学期の時間割を取得する

• 成績、単位、クラス平均点、最高点を照会する（上流が提供する場合）

• 今後一定期間の楽学カレンダーイベントを照会する

• 異なるソースのデータを組み合わせて質問に答える。例：「来学期の授業の先生について、みんなはどう評価しているか」

すべてのツールは読み取り専用です。本プロジェクトは投稿、いいね、コメント、課題提出、成績変更、その他いかなる学校データの修正も行えません。

Related MCP server: MCP-Server-CollageAI

実機デモ

以下のスクリーンショットは Windows 上の OpenCode cli による実機呼び出しのものです。具体的な回答は、使用するモデルが MCP から返されたデータに基づいて生成したものであり、プロジェクト作者の見解を表すものではなく、モデルやデータの更新に応じて変化する可能性があります。

今日の投稿要約

Agent は list_today_posts を呼び出して当日の投稿を取得し、タイトル、内容、インタラクション状況に基づいて簡潔な要約を生成します。

教員と授業評価

Agent はまず教員に対応する授業を検索し、次に get_course_reviews を呼び出して授業メタデータ、評価、コメント、履歴情報を集約します。

専攻方向の議論

授業ライブラリに完全一致するエントリがない場合、Agent は BIT101 の投稿をさらに検索して関連する議論を読み取ることができ、複数の MCP ツールを連携して使用する効果を示しています。

楽学カレンダー

Agent は 7〜90 日以内の楽学イベントを照会できます。有効なカレンダーに直近のタスクがない場合は、空リストを正常に返し、「タスクなし」をインターフェース障害と誤判定しません。

使用前の準備

現在推奨される環境：

• Windows 10/11、またはデスクトップブラウザと利用可能なシステム keyring を備えた Linux（Fedora 43 + niri で実測済み）

• Python 3.11 以降

• uv

• ローカル stdio MCP をサポートするクライアント。例：Codex、OpenCode、Cursor、Claude Code

• BIT101 アカウント

• 時間割・成績の照会には、北京理工大学の統一認証アカウントも必要です。一部のログインでは SMS 認証が必要な場合があります

• 楽学の照会には、楽学からプライベートカレンダー購読アドレスを一度エクスポートする必要があります

インストール

Agent に任せる（推奨）

Agent がターミナルコマンドを実行でき、自身の MCP 設定を変更できる場合は、以下の文章をそのまま Agent に送信できます：

请帮我安装并配置 BIT101 MCP：
https://github.com/tiny-paris/BIT101-mcp

要求：
1. 先阅读仓库 README，尤其是“认证、安全与隐私”部分，并告诉我它会访问哪些服务。
2. 检查本机是否安装 Python 3.11+、Git 和 uv；缺少时说明后再安装。
3. 优先使用以下命令安装为用户级工具：
   uv tool install "git+https://github.com/tiny-paris/BIT101-mcp.git"
4. 识别我当前使用的 MCP 客户端，将 bit101-mcp 配置为用户级/全局 stdio MCP，
   名称使用 bit101，单次工具执行超时至少设置为 360 秒。
5. 如果找不到命令，运行 uv tool dir --bin，并在 MCP 配置中使用
   bit101-mcp（Windows 为 bit101-mcp.exe）的绝对路径。
6. 重启或重新加载 MCP，验证服务器已连接并能列出工具。
7. 不要在聊天、命令行参数、配置文件或环境变量中向我索要或写入账号、密码、
   短信验证码、Cookie、token 或乐学订阅 URL。需要认证时，只让我在 MCP 自动打开的
   127.0.0.1 临时页面中操作。
8. 不要修改默认上游地址。完成后告诉我修改了哪些配置文件以及验证结果。

Agent がインストールを完了したら、新しい会話で「今日の BIT101 投稿を要約して」と質問するだけで、初回のオンデマンド認証がトリガーされます。

ソースからインストール

リポジトリが公開されたら、以下を実行できます：

git clone https://github.com/tiny-paris/BIT101-mcp.git
cd BIT101-mcp
uv sync --all-groups
uv tool install .

uv tool install . は bit101-mcp をユーザーレベルのコマンドとしてインストールします。以下のコマンドで uv の実行ファイルディレクトリを確認できます：

uv tool dir --bin

MCP クライアントが bit101-mcp を見つけられない場合は、クライアントを再起動するか、設定でそのディレクトリ内の bit101-mcp.exe の絶対パスを使用してください。

ソースディレクトリ内でのみ実行

開発やテスト時には、コマンドをインストールせずに実行することもできます：

uv sync --all-groups
uv run bit101-mcp

stdio MCP は正常に起動するとプロトコルメッセージを静かに待機するため、「フリーズした」ように見えるのは正常です。通常の対話型コマンドとして扱わず、そのターミナルにアカウントやパスワードを入力しないでください。

[!NOTE] プロジェクトが PyPI に公開されて初めて、簡単な uvx bit101-mcp がサポートされます。現在の README は PyPI パッケージの存在を前提としていません。

依存関係の説明

プロジェクトは 7 つのランタイム直接依存関係を宣言しています。これらはすべて「MCP プロトコルで必須」というわけではなく、現在の完全な機能にそれぞれ必要なコンポーネントです：

したがって、現在の単一パッケージ版では、これら 7 つはすべて実行時依存関係です。ただし機能面では、icalendar と python-dateutil は楽学専用であり、将来オプション機能に分割する場合は追加の依存関係に変更できます。現在分割するとインストールとエラー報告の複雑さが増し、節約できるサイズも限られています。

uv.lock には anyio、httpcore、certifi などの間接依存関係も表示されます。これらは上記のライブラリによって自動的に導入されるもので、プロジェクトが直接呼び出すトップレベルコンポーネントではなく、個別に手動インストールまたは削除すべきではありません。

以下の依存関係は開発と公開のみに使用され、通常の実行時依存関係としてはインストールされません：

MCP クライアントの設定

初回の学校認証には最大で数分かかる場合があるため、単一ツール呼び出しのタイムアウトは 360 秒に設定することをお勧めします。設定完了後は MCP クライアントを再起動して、新しいサービスプロセスを起動する必要があります。

Codex

Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップの Codex ホストは、config.toml の MCP 設定を共有します。公式ドキュメントは Codex MCP ドキュメント を参照してください。

まず CLI で追加します：

codex mcp add bit101 -- bit101-mcp
codex mcp list

次にユーザーレベルの %USERPROFILE%\.codex\config.toml を確認し、ツールのタイムアウトを補足します：

[mcp_servers.bit101]
command = "bit101-mcp"
tool_timeout_sec = 360

特定の信頼できるプロジェクトでのみ有効にしたい場合は、同じ設定をそのプロジェクトの .codex/config.toml に配置できます。ユーザーレベルの設定は任意のディレクトリと新しい会話で使用できます。

コマンドが Codex の PATH にない場合は、絶対パスに変更できます：

[mcp_servers.bit101]
command = 'C:\path\to\bit101-mcp.exe'
tool_timeout_sec = 360

OpenCode

本プロジェクトは以下の従来の OpenCode 設定で Windows 実機テストを完了しています。プロジェクトルートの opencode.json に配置するとそのプロジェクトのみに有効です。任意のディレクトリで使用したい場合は、ユーザーレベルの ~/.config/opencode/opencode.json（Windows では通常 %USERPROFILE%\.config\opencode\opencode.json）に配置してください。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bit101": {
      "type": "local",
      "command": ["bit101-mcp"],
      "enabled": true,
      "timeout": 360000
    }
  }
}

接続を検証します：

opencode mcp list

ソースディレクトリでのみ起動できる場合は、通常、設定が相対コマンドを使用しており、グローバルインストールされていないことが原因です。bit101-mcp をインストールするか、command を .venv\Scripts\bit101-mcp.exe の絶対パスに変更してください。

OpenCode V2 の設定構造は異なり、サービスは mcp.servers の下にあり、実行タイムアウトは mcp.timeout.execution にあります。OpenCode MCP 公式ドキュメント を基準にしてください：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timeout": {
      "execution": 360000
    },
    "servers": {
      "bit101": {
        "type": "local",
        "command": ["bit101-mcp"]
      }
    }
  }
}

Cursor

Cursor MCP ドキュメント によると、グローバル設定は ~/.cursor/mcp.json に、プロジェクト設定は .cursor/mcp.json に配置します：

{
  "mcpServers": {
    "bit101": {
      "command": "bit101-mcp",
      "args": []
    }
  }
}

保存後 Cursor を再起動し、Agent の利用可能なツールリストで bit101 が有効になっていることを確認します。

Claude Code

Claude Code MCP ドキュメント に従って、ユーザーレベルの stdio サービスを追加します：

claude mcp add --scope user bit101 -- bit101-mcp
claude mcp list

汎用 stdio 設定

その他の MCP クライアントは、ローカル stdio プロセスを 1 つ設定するだけで済みます：

{
  "command": "bit101-mcp",
  "args": []
}

アカウント、パスワード、Cookie、トークン、楽学 URL を MCP 設定、環境変数、ツールパラメータに書き込まないでください。

使い始める

設定完了後は、Agent の会話で直接質問するだけで、バックグラウンドサービスを手動で起動する必要はありません。例：

BIT101 コミュニティと授業

总结一下今天 BIT101 都有哪些帖子。
查找最近关于“数据结构”的讨论。
如何评价某某老师的某门课？请区分普遍评价和少数意见。
查找“特立自动化”相关讨论，并列出信息来源。

時間割と成績

我今天有什么课？
我下周有什么课？按实际日期和开始时间排序。
列出本学期完整课表。
列出我的所有成绩，包括课程、学期、学分、成绩、班级平均分和最高分。

「今週/来週」と尋ねると、サーバーは現在の日付に基づいて正確な週を計算し、starts_at、ends_at などの完全な時間を返します。Agent が教学週や時限の時間を自分で推測する必要はありません。

楽学

未来 14 天有哪些乐学任务？按截止时间排序。
看看未来 30 天的乐学日历。

利用可能なツール

成功結果は一律で次の形式です：

{
  "ok": true,
  "data": {}
}

失敗結果には上流のスタックトレースや認証情報は含まれません：

{
  "ok": false,
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "service": "bit101",
    "message": "BIT101 is temporarily unavailable.",
    "retryable": true
  }
}

技術原理

中核は 4 層に分かれています：

1. MCP ツール層：投稿、授業、時間割、成績、タスクなどのユーザー概念のみを公開し、Cookie、チャレンジトークン、内部サービス識別子は公開しません。

2. クライアント層：BIT101 API と学校データゲートウェイをそれぞれ処理し、リクエスト失敗時にセッションの有効期限切れを判断し、回復可能な再試行を 1 回だけ行います。

3. 標準化層：異なる上流フォーマットを安定した JSON フレンドリーなフィールドに変換し、上海タイムゾーンの日付、教学週、授業時間、成績、ICS イベントの解析を担当します。

4. 認証・ストレージ層：必要なときだけローカルページを開きます。パスワードは MCP パラメータに入らず、成功後は再利用可能なセッションのみを保存します。

MCP は stdio transport を使用します。標準出力は MCP プロトコルデータのみを送信し、実行ログは標準エラーにのみ書き込まれ、ログがプロトコル通信を壊すことはありません。

認証フロー

ブラウザの BIT101 ログインを直接再利用できないのはなぜ？

ブラウザの Cookie はブラウザ自身のセキュリティ空間に属し、MCP は独立したローカルプロセスです。本プロジェクトは意図的に Chrome/Edge の Cookie データベースを読み取らず、ブラウザ拡張機能のインストールも要求しません。これにより初回認証が 1 回増えますが、MCP がユーザーの全ブラウザ資格情報をスキャンすることを回避できます。

新しい Agent 会話を開いてもログイン状態はクリアされません。MCP は起動時に保存済みセッションを読み取り検証します。セッションが存在しない、上流が無効と判定した、認証ゲートウェイの一時チャレンジが期限切れになった、またはシステム資格情報ストアが利用できない場合にのみ再ログインします。

BIT101

コミュニティツールを初めて呼び出すとき：

1. MCP は 127.0.0.1 のランダムポートで一時ページを起動します。

2. ユーザーはローカルページで学籍番号と BIT101 パスワードを入力します。

3. ローカルプロセスは既存の BIT101 ログインプロトコルに従ってパスワードを処理し、HTTPS で BIT101 API にリクエストします。

4. ログイン成功後、返された BIT101 セッションのみをシステム資格情報マネージャーに保存します。元のパスワードは永続化されません。

5. 一時ページが閉じられ、元のツール呼び出しが続行されます。

学校の時間割と成績

時間割と成績は学校の個人データ能力に由来し、BIT101 コミュニティセッションとは別の「鍵」です。初回呼び出し時に、ローカルページは統一認証アカウント、パスワード、および必要な場合は SMS 認証コードを収集し、HTTPS で既存の BIT-Login REST ゲートウェイに送信します。MCP が保存するのはゲートウェイが返す短期チャレンジセッションであり、学校のパスワードは保存しません。

楽学カレンダー

現在の BIT-Login REST ゲートウェイには、本プロジェクトが呼び出せる楽学カレンダーインターフェースがなく、プロジェクトは学校の CAS/SSO を再実装しません。したがって MVP では、ユーザーが楽学の カレンダー → カレンダーをエクスポート ページでプライベート購読アドレスを生成し、ローカル接続ページに一度貼り付ける必要があります。

接続ページは実際に iCalendar コンテンツをダウンロードして検証し、有効な購読のみが Connected と表示されます。通常の calendar/view.php ページは拒否されます。購読アドレスは Agent や MCP ツールの結果には入らず、システム資格情報マネージャーに保存されます。直近のイベントがない有効なカレンダーは空リストを返します。

認証・セキュリティ・プライバシー

先に結論

本プロジェクトはパスワードが Agent、チャット履歴、ログに入るリスクを低減しますが、「ゼロリスク」を約束することはできません。ローカル MCP をインストールすることは、ネットワークに接続できるローカルプログラムをインストールすることに相当します。ユーザーはプロジェクトのソースコード、インストールパッケージ、依存関係、設定されたリモート認証サービスを信頼する必要があります。

特に 2 つの文を区別する必要があります：

• パスワードは Agent/LLM に送信されません：これは本プロジェクトが明確に実装した境界です。

• パスワードはこのマシンにのみ存在します：そうではありません。学校の統一認証パスワードは、ローカル MCP が HTTPS で設定されたリモート BIT-Login ゲートウェイに送信して認証を完了する必要があります。

どの情報がどこへ行くのか？

デフォルトの上流アドレス：

• BIT101 API：https://bit101.flwfdd.xyz

• BIT-Login REST：https://login.bit101.flwfdd.xyz

HTTPS は一般的なネットワーク盗聴を防げますが、サーバー運営者への信頼の代替にはなりません。学校のパスワードがリモートゲートウェイを経由することを気にするユーザーは、時間割と成績ツールを有効にすべきではありません。

実装済みの保護策

• 一時 HTTP サービスは 127.0.0.1 のみにバインドし、OS が割り当てるランダムポートを使用します。

• 各認証で 256 ビットのランダム state を使用し、定数時間比較で偽造送信を防ぎます。

• ページはキャッシュ、外部コンテンツ、iframe、referrer、MIME 推測を無効にします。

• ページは成功、キャンセル、タイムアウト後にリスニングを停止します。

• パスワード、認証コードはファイルに書き込まれません。コードはリクエスト後できるだけ早く関連変数の参照をクリアします。

• セッションは Python keyring を通じて OS 資格情報ストア（Windows Credential Manager、または Linux の Secret Service/keyring バックエンド）に書き込まれます。利用できない場合は現在のプロセスのメモリ内にのみ保存され、平文ファイルにフォールバックしません。

• ログはパスワード、認証コード、Cookie、Bearer token、Authorization ヘッダーをマスクします。

• 楽学アドレスは bit.edu.cn ドメイン配下の HTTPS である必要があり、有効な iCalendar を返す必要があります。

• ツールはすべて読み取り専用としてマークされ、学校やコミュニティのデータを変更する機能は提供しません。

ユーザーが注意すべきこと

• 信頼できるリポジトリまたは信頼できる公開ページからのみインストールし、可能な限りソースコードと公開ハッシュを確認してください。

• ローカル認証ページのアドレスは http://127.0.0.1:<ランダムポート>/connect で始まる必要があります。

• Agent のチャットボックス、MCP パラメータ、Issue、ログにパスワード、認証コード、Cookie、トークン、楽学 URL を決して送信しないでください。

• 信頼できない公共のコンピューターで個人の学校アカウントを使用しないでください。

• 楽学購読 URL は「取得すれば読み取れる」プライベートリンクであり、パスワードと同様に保護する必要があります。漏洩が疑われる場合は楽学で再生成してください。

• 成績・時間割を照会すると、対応するデータが現在の Agent に提供されます。使用するモデルとクライアントのデータポリシーに基づいて、有効にするかどうかを自分で判断してください。

ローカルセッションのクリア

Windows では コントロールパネル → 資格情報マネージャー → Windows 資格情報 を開きます。Linux では現在のデスクトップ環境が使用する Secret Service 管理ツール（一般的には GNOME Keyring または KDE Wallet）を開きます。サービス名 bit101-mcp の以下のエントリを削除します：

• bit101-session

• school-session

• lexue-calendar-url

削除後、次に対応するツールを呼び出すと再認証されます。Python パッケージをアンインストールしても、これらのシステム資格情報は自動的に削除されません。Linux で利用可能な keyring バックエンドがない場合、セッションは現在のプロセスのメモリ内にのみ保存され、MCP を再起動すると再ログインが必要になります。

設定項目

非秘密パラメータのみ環境変数で設定できます：

資格情報とセッションはツールパラメータや環境変数では設定できません。上流アドレスを変更することは新しいサービス運営者を信頼することを意味するため、慎重に使用してください。

よくある質問

Agent をプロジェクトディレクトリで起動する必要がありますか？

いいえ。uv tool install . でコマンドをインストールし、MCP をクライアントのユーザーレベル設定に書き込めば、任意のディレクトリから使用できます。プロジェクトルートの opencode.json、.cursor/mcp.json、.codex/config.toml は対応するプロジェクトにのみ有効です。

なぜ初回使用時にブラウザが開くのですか？

認証はオンデマンドでトリガーされます。最初の投稿照会には BIT101 セッションが必要です。最初の時間割/成績照会には学校セッションが必要です。最初の楽学照会にはプライベートカレンダー購読も必要です。パスワードと購読アドレスはチャットを経由できないため、一時的なローカルページで収集します。

BIT101 のウェブページにはログイン済みなのに、MCP がまだログインを要求するのはなぜ？

ウェブセッションはブラウザの Cookie に保存されています。MCP はブラウザの Cookie を読み取らないため、独自の最小セッションを確立する必要があります。これにより初回ログインの利便性が 1 回犠牲になりますが、ブラウザの全ログインデータへの直接アクセスを回避できます。

新しい会話でたまに再ログインが必要なのはなぜ？

新しい会話はセッションを積極的にクリアしませんが、MCP は上流セッションを検証します。セッションの期限切れ、サーバーによる失効、認証ゲートウェイのチャレンジ無効化、またはシステム資格情報ストアが利用できない場合に再ログインします。ログイン成功直後に再起動して再度プロンプトが表示される場合は、システム資格情報ストアに bit101-mcp エントリが存在するか確認してください。

楽学で Connected と表示されるのに、タスクがないのはなぜ？

購読アドレスが iCalendar 検証を通過した場合、空リストは通常、選択した時間範囲内に実際にイベントがないことを意味します。照会範囲を 7 日から 30 日に拡大して確認できます。

学校ツールが遅いのはなぜ？

初回の学校認証、SMS 認証、成績明細の取得には時間がかかる場合があります。MCP ツールのタイムアウトを 360 秒に設定し、現在の呼び出しの完了を待ってください。複数の学校ツールを同時に再試行しないでください。

bit101-mcp コマンドが見つからない場合は？

uv tool dir --bin を実行してインストールディレクトリを見つけ、PATH に追加するか、MCP 設定に bit101-mcp.exe の絶対パスを直接記入してください。変更後はクライアントを再起動します。

エラーコード

すべてのエラーは洗浄され、パスワード、Cookie、トークン、Authorization ヘッダー、元のスタックトレース、完全な機密リクエストは返されません。

開発

プロジェクト構造：

src/bit101_mcp/
├── server.py           # MCP 入口、工具注册和服务器说明
├── tools/              # Agent 可见的只读工具
├── clients/            # BIT101 与学校上游客户端
├── auth/               # 本地浏览器认证、状态机和凭据存储
├── models/             # 数据标准化、周次和 ICS 解析
└── logging_utils.py    # stderr 日志和秘密脱敏

開発依存関係をインストールしてチェックを実行：

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv build

メンテナーは公開前に、公開リポジトリに含まれないモックテストでデータ標準化、認証状態、秘密のマスク、再試行フローを検証します。これらのテストは実際のアカウントを必要としません。実アカウントの統合テストは手動・オプションのまま維持し、テスト資格情報をリポジトリや CI にコミットすべきではありません。

謝辞

BIT101 プロジェクトとすべてのコントリビューターに感謝します。先輩方が長期間維持してきたコミュニティ、授業評価、キャンパスデータインターフェース、認証ツールは、学生のキャンパスライフに大きな利便性をもたらし、本プロジェクトの重要な基盤にもなっています。

本プロジェクトは特に以下のプロジェクトが提供するインターフェースとドキュメントを参照または使用しています：

• BIT101

• BIT101-GO

• BIT101-Android

• BIT-Login

BIT101 MCP は独立して開発された非公式 MCP クライアントであり、ネットワークインターフェースを通じて関連サービスと対話します。本リポジトリの MIT License は本プロジェクトのオリジナルコードにのみ適用され、いかなる上流プロジェクトのライセンスも代替または変更しません。

現在の制限

• Windows では主要フローの実機テストが完了しています。Fedora 43 + niri での動作は確認済みですが、他の Linux デスクトップ環境はまだ個別に検証されていません。

• 楽学では、エクスポートしたプライベートカレンダー購読アドレスを一度手動で貼り付ける必要があります。

• 学校セッションの有効期間は上流ゲートウェイが決定するため、長期間のログイン不要を保証できません。

• 成績の平均点と最高点は、上流が各授業の明細を提供するかどうかに依存します。

• PyPI パッケージと Windows スタンドアロン実行ファイルはまだ公開されていません。

• 書き込み操作は一切提供しません。

ライセンス

このプロジェクトは MIT License を採用しています。著作権と許諾表示を保持することを条件に、使用、修正、配布、改善の提出を歓迎します。

貢献

Issue と Pull Request の提出を歓迎します。問題を報告する際は、以下を提供してください：

• オペレーティングシステム、Python、uv、MCP クライアントのバージョン

• 使用したツール名と、マスク処理されたエラーコード

• ローカル認証ページが表示されたかどうか

• 再現手順

学籍番号、パスワード、認証コード、Cookie、token、完全なリクエストヘッダー、乐学 URL、その他の個人情報を提出しないでください。