Colab-MCP (unofficial)

Colab-MCP

AI エージェント（Claude、または任意の MCP クライアント）がGoogle Colab をエンドツーエンドで利用できるMCP サーバーです。GPU／TPU ランタイムの作成と停止、コードの実行、ノートブックでのセル単位の作業、長時間のバックグラウンドジョブの起動、VM との間でのファイルやフォルダーの転送ができます。

Google 公式の Colab CLI（google-colab-cli）上に構築された、シンプルで安全なレイヤーです。Colab を再実装するものではなく、ブラウザーのタブにも依存しません。

🇪🇸 Resumen en español al final de este archivo.

クイックスタート

uv と、サインインを一度済ませた Google 公式の Colab CLI が必要です（macOS または Linux）。

uv tool install google-colab-cli
colab sessions        # sign in ONCE (open the link, paste the code)
claude mcp add colab-cli -e COLAB_MCP_WORKDIR="$HOME/colab-work" -- uvx colab-cli-mcp

これによりサーバーが Claude Code に登録され、初回起動時に uvx が PyPI からダウンロードします。Claude Desktop、その他のクライアント、シークレット、オプションの Drive ツールについては、インストールをご覧ください。

ステータス

• シミュレートした CLI でテスト済み（118 件のチェックに加え、シミュレートした Drive API に対する Drive のチェック 129 件、Drive のマウントに関するチェック 28 件、ローカルのクリーンアップに関するチェック 17 件。tests/）：実際の MCP クライアントが stdio 経由でサーバーと通信し、通常は VM 上で実行されるコードをサンドボックスフォルダー内で実際に実行します。
• 実環境で一度検証済み。 実際の Colab セッション（macOS、クライアントは Claude）で、ランタイムの作成、コードの実行、ログをポーリングする長時間のバックグラウンドジョブ、チャットからの Drive のマウント（下記）、セッションの停止を行い、実際のバッチワークロードを 1 件実行しました（項目 10 件、エラー 0 件）。これは 1 回の実行であり、ベンチマークではありません。
• PyPI で公開済み。パッケージ名は colab-cli-mcp、バージョンは 0.1.0 です。公開済みのパッケージをクリーンな環境にインストールし（pip と uvx）、stdio 経由で 42 個のツールが一覧表示されることを確認しました。このチェックは Linux で実施しました。macOS で Claude と uvx を使う方法は、まだ確認していません。
• 実環境での検証がまだ済んでいない項目： Google Drive API ツール（drive_*）、ノートブックのセル単位での実行、フォルダーのアップロードとダウンロード、および既知の未確認事項に記載された動作です。その他の MCP クライアント（Cursor、Codex、Windsurf）と Linux ではテストしていません。
• Linux と macOS のみ対応しています（Colab CLI は Windows をサポートしていません）。

ツール（42 個＋オプションの Drive ツール 8 個）

分野	ツール
ランタイム	colab_new、colab_ensure_session、colab_sessions、colab_status、colab_runtime_info、colab_restart_kernel、colab_url、colab_usage、colab_stop、colab_install
コードの実行	colab_exec（コードまたはファイル。呼び出し間でカーネルの状態を保持）、colab_run（1 回限り：新しい VM → スクリプト → 解放）
ノートブック（ローカルの .ipynb）	colab_notebook_create、_list、_read、_add_cell、_edit_cell、_delete_cell、_move_cell、_clear_outputs、_run_cell、_run_all、_to_script、_delete
長時間ジョブ	colab_job_start、_status、_logs、_cancel、_list
ファイル	colab_upload、colab_download、colab_upload_dir、colab_download_dir、colab_ls、colab_rm、colab_log
VM 上の Drive	colab_drive_status、colab_drive_mount_start、colab_drive_mount_finish、colab_drive_project_dir（大規模プロジェクトと Driveを参照）
ローカルの使用状況	colab_local_footprint、colab_local_cleanup（ファイルの保存場所を参照）

一般的なフロー：

• 対話型： colab_ensure_session(gpu="T4") → colab_notebook_create → セルを追加 → colab_notebook_run_cell で 1 つずつ実行（変数は保持されます）→ 出力を読み取る → colab_stop。
• バッチ： colab_upload_dir → colab_job_start("python -u train.py") → colab_job_logs をポーリング → colab_download_dir → colab_stop。

Google Drive のプロジェクトとノートブックは、個別に有効化するオプション機能です（下記）。意図的にどこにも含めていないもの：ツール経由のサインイン、colab auth、repl、console、ssh、edit。これらは対話型であり、ツール呼び出しでは動作しません。

セキュリティモデル

• ローカルパスは COLAB_MCP_WORKDIR 内に制限されます。 ../、絶対パス、および制限範囲外へ抜けるシンボリックリンクは、実行前に拒否されます。
• シークレットがモデルに渡ることはありません。 COLAB_MCP_ENV_FILE は、ローカルの NAME=value 形式のファイルを指定します。モデルが渡すのは名前のみです（secrets=["OPENROUTER_API_KEY"]）。値は --env を使ってカーネルに渡され、すべての結果から除去されます。既知の制限：コマンドの実行中、CLI が値を引数として受け取るため、他のローカルユーザーがプロセス一覧で値を確認できます。
• シェルは使用しません。 CLI は引数リストで実行されます。セッション名、GPU の種類、パッケージ指定子、ジョブ ID は検証されます。VM 上で実行するコードに埋め込まれるユーザー制御可能な値は、すべて repr() を通します。
• フォルダー転送には保護策があります。 アップロードでは .git、キャッシュ、シンボリックリンク、シークレットと思われるファイル（.env、*.pem、*.key など）を除外します。ダウンロードでは、展開先の外に出るパス（zip-slip）を含むアーカイブや、サイズ制限を超えるアーカイブを拒否します。
• お使いのコンピューター上で完全に削除することはありません。 colab_notebook_delete はファイルを .colab-mcp-trash/ に移動します。colab_rm は VM のみを対象とし、ルートに相当するパスは拒否します。
• 出力は COLAB_MCP_MAX_OUTPUT 文字に制限され、ターミナルのカラーコード（トレースバック）は除去されます。
• 実行するコードは、お客様のアカウントを使用して Google のマシン上で実行され、計算ユニットを消費します。 不要になったセッションは停止してください。

VM 上の大規模プロジェクトと Drive

セッション終了後も保持する必要がある大規模なデータセット、チェックポイント、結果には、VM 上で Google Drive をマウントしてください。これは、以下で説明するオプションの「Drive notebooks」機能とは別のもので、Colab CLI 独自のサインインを使用します。

1. ターミナルを使わず、チャットからマウントします。 colab_drive_mount_start は疑似ターミナルで公式の colab drivemount を実行します（CLI 自体はブラウザーを開かず、リンクを表示して Enter キーを待つだけです）。その後、ブラウザーで Google の承認ページを開きます。リンクはチャットで繰り返し表示されません（アカウントのメールアドレスが含まれているため）。ブラウザーを開けなかった場合、または show_link=true の場合にのみ返されます。お客様が「許可」をクリックし（エージェントが認証情報やコードを見ることはありません）、そのことをエージェントに伝えると、colab_drive_mount_finish が CLI が待機していた Enter キーを送信し、colab_drive_status がマウントを確認します。開かれるのは https://*.google.com のリンクのみです。保留中のマウントは 15 分後に終了し、セッションごとに同時に存在できるマウントは 1 つだけです。必要であれば、ターミナルで colab drivemount -s SESSION を実行しても引き続き利用できます。 マウントすると、その VM 上で実行されるコードが Drive 全体にアクセスできるようになります（Colab ではアクセス範囲を限定できません）。必要な場合にのみマウントし、その後セッションを停止してください。
2. エージェントが colab_drive_project_dir("my-project") を呼び出すと、/content/drive/MyDrive/Colab-MCP/my-project が作成され、パスが返されます。データセット、チェックポイント、出力はそこに保存してください。
3. 作業が終わったらセッションを停止してください。その Drive フォルダー内のファイルは残りますが、VM 上のそれ以外のものはすべて失われます。

保護策：ファイルツール（colab_upload*、colab_download*、colab_ls、colab_rm）は、COLAB_MCP_DRIVE_PROJECTS でフォルダー名を変更した場合も含め、/content/drive/MyDrive/Colab-MCP/ の外にある Drive パスをすべて拒否します。これには ..、相対パス、大文字・小文字の違いを利用した回避も含まれます。colab_drive_status がファイル一覧を表示することはありません。

残存リスクについて、明確に説明します： Drive をマウントすると、VM 上で実行されるあらゆるコード（colab_exec、colab_run、ジョブ、ノートブックのセル）が Drive 全体を読み取り、変更できるようになります。パスガードが対象とするのはこのサーバーのファイルツールのみで、VM 上で作成されたシンボリックリンクは検出できません。必要な場合にのみマウントし、実行するコードを確認してから、その後セッションを停止してください。

ファイルの保存場所（およびコンピューターに残るものがごくわずかな理由）

場所	内容	理由
Colab VM のディスク（T4 で空き容量約 200 GB を確認済み ⚠️ 保証されません）	データセット、トレーニングなど、容量の大きいもの	高速で無料ですが、セッション終了時に消去されます
Drive、フォルダー Colab-MCP/<project>/	保存が必要なノートブックと結果	セッションをまたいで保持されます。このツールがアクセスできる Drive 内の唯一の場所です
お使いのコンピューター	ほとんど何もありません。ノートブックの編集中に使う一時的な作業用コピーだけです	以下のとおり自動的にクリーンアップされます

ローカルの保存容量に関するルール（footprint.py）：

• 転送用 ZIP は使用後すぐに削除され、1 時間後に一掃されます。保存済みのプロットは 2 日後（COLAB_MCP_IMAGE_DAYS）、ローカルで「削除」したノートブックは 7 日後（COLAB_MCP_TRASH_DAYS、0 = 保持）、Drive のノートブックの作業用コピーは 24 時間後（COLAB_MCP_DRIVE_COPY_HOURS、0 = 保持）に削除され、保存時にもすぐに削除されます。一掃処理はサーバー起動時と colab_local_cleanup の実行時に行われます。
• 削除対象となるのは .colab-mcp/ と .colab-mcp-trash/ 内のファイルだけです。シンボリックリンクはたどりません。お使いのノートブックやデータには一切触れません。
• ダウンロード前に、ディスクに少なくとも COLAB_MCP_MIN_FREE_GB（既定値は 5）の空き容量があること、および作業フォルダーが COLAB_MCP_WORKDIR_MAX_GB（既定値は 20、0 = 上限なし）を超えないことを確認します。colab_local_footprint で数値を確認できます。大きなデータは VM または Drive に置き、結果のみをダウンロードしてください。

Google Drive：プロジェクトとノートブック（オプトイン）

既定では無効です。COLAB_MCP_DRIVE=1（Drive を設定するとインストーラーが設定します）にすると、以下のツールだけが表示されます。

ツール	機能
drive_sign_in	お使いのコンピューターでブラウザーウィンドウを開き、ご自身で「許可」をクリックします。コードやトークンがチャットを経由することはありません
drive_project_create / drive_project_list	Colab-MCP 内に Colab プロジェクトごとのフォルダーを作成します。フォルダーの作成はできますが、削除や名前の変更はできません
drive_notebook_create	ノートブックを作成します（空のひな形、または出力を削除したローカルの .ipynb）。プロジェクト内に作成することもできます
drive_notebook_list	このサーバーが作成したノートブックを一覧表示します
drive_notebook_open / drive_notebook_save	ノートブックを一時的なローカルコピーにダウンロードし、colab_notebook_* ツールで編集して、同じファイルに内容を書き戻します。保存するとローカルコピーは削除されます
drive_notebook_delete	ノートブックを Drive のゴミ箱に移動します（完全に削除されることはありません）

Drive 内の構成：Colab-MCP/<project>/<notebook>.ipynb。Google の権限（drive.file）でアクセスできるのは、このアプリが作成したファイルとフォルダーだけです。そのため、既存の「Colab Notebooks」フォルダーやその他すべての項目は、このアプリからは見えません。

エージェントの動作をこの範囲に厳密に制限するスキルは、skills/colab-drive-notebooks/SKILL.md にあります。このフォルダーを ~/.claude/skills/（Claude Code）にコピーするか、お使いのクライアントでスキルとして追加してください。

誰が何を担当するか

認証情報を共有することはありません。**各ユーザーが自分でサインインし、トークンは各自のディスクにのみ保存されます。**以下の 2 つの OAuth クライアントから、一度だけ選択します。このプロジェクトがトークンを見ることはありません。モデルがサインインリンク、コード、トークンを見ることもありません。

クイックスタート（すべてのユーザー向け）

PyPI から：

uvx --from colab-cli-mcp colab-cli-mcp-drive login     # asks once how you want to sign in, remembers it, signs you in
claude mcp add colab-cli -e COLAB_MCP_WORKDIR="$HOME/colab-work" -e COLAB_MCP_DRIVE=1 -- uvx colab-cli-mcp

このリポジトリのクローンから bash install.sh を実行すると、「Drive を今すぐセットアップしますか？」と尋ねられ、以下の初回設定が実行され、Drive ツールを有効にした状態でサーバーが登録されます。手動で行う場合：

git clone https://github.com/amgallego8/Colab-MCP ~/Colab-MCP && cd ~/Colab-MCP
uv sync
uv run colab-cli-mcp-drive login     # same login, run from the clone

login では、ご自身の Google Cloud「デスクトップアプリ」クライアントを作成する手順を案内します（約 10 分、初回のみ、無料。手順は以下を参照）。ダウンロードした JSON のパスを指定すると、ファイルはご自身のために保存されます（0600）。プロジェクトについてはご自身が Google に責任を負います。その後のログインは、リンクがブラウザーで開き、［許可］をクリックすれば完了です。コードを貼り付ける必要はありません。

共有のワンクリッククライアントはまだ提供されていません。 このリポジトリが1,000 スターに達した場合、メンテナーは共有クライアントを公開する予定です（Google Cloud のセットアップなしでログインできる、すぐに使えるクライアントです）。これは計画であり、確約ではありません。そのコードはすでに存在します。ビルドに colab_cli_mcp/shared_client.json が含まれている場合、login は 共有 と 独自 の選択メニューを表示します。

共有クライアントは、明示的に選択しない限り使用されません（ターミナルでの回答、または --shared）。選択内容は ~/.config/colab-mcp/drive/preference.json に保存されます。その後、Drive ツールがアクセスを必要とし、有効なトークンがない場合（初回使用時、または Testing モードのアプリで 7 日間の有効期限が切れた後）、サーバー自体がブラウザーで同意ページを開き、クリックされるのを待ちます。クリック後、リクエストを再度実行してください。ログイン、drive.file スコープ、トークンファイル、すべての安全策は、どちらの場合も同じです。

MCP クライアントでは、drive_notebook_delete の呼び出しごとの承認を有効にしたままにしてください。このプロンプトが実際の人間による確認となります。サーバー側でこれを強制することはできません。uvx --from colab-cli-mcp colab-cli-mcp-drive status（またはクローンから uv run colab-cli-mcp-drive status）を実行すると、設定内容を確認できます。

利用を終了するには、colab-cli-mcp-drive logout を実行します（トークンが削除され、Google で失効処理が行われます）。失効を確認できなかった場合は、https://myaccount.google.com/permissions でアプリを削除してください。

独自のクライアントを作成する（login で案内される手順）

1. Google Cloud コンソールでプロジェクトを作成し、Google Drive API を有効にします（ガイド）。
2. 同意画面／Google Auth Platform を設定します（ガイド）。Audience で External を選び、Test users にご自身を追加します。Data Access → Add or Remove Scopes では .../auth/drive.file のみを追加します。
3. Google Auth platform → Clients → Create Client → Desktop app を選択します（Google の手順）。JSON をダウンロードし、そのパスを login に指定します。

メンテナー向け：共有クライアントを公開する

上記の手順でクライアントを作成し（専用の Google アカウントとプロジェクトを使うことを推奨）、JSON を colab_cli_mcp/shared_client.json に配置して、明示的にコミットします（git add -f。このファイルはデフォルトで git の対象外です）。デスクトップアプリのクライアントシークレットは、設計上、機密情報ではありません。ただし、プロジェクト、同意画面（サポートメール、プライバシーポリシーのリンク）、および Google の各種確認要件はご自身の責任になります。TERMS.md を参照してください。

脅威モデル（保護するものと保護しないもの）

レイヤー	提供される保護
スコープ drive.file のみ	トークンでアクセスできるのは、この OAuth クライアントが作成したファイルのみです。以下のすべての対策が機能しなかった場合でも、Drive のほかのファイルを読み取ったり削除したりすることはできません。Google はこのスコープを非機密として分類しています。
独自の OAuth クライアント	他のユーザーやベンダーのクライアントがファイルにアクセスすることはできず、自分のプロジェクトからクライアント全体を取り消せます。
トークンの取り扱い	ファイルは 0600 に設定され、グループまたはその他のユーザーが読み取り可能な場合は拒否されます。drive.file 以外のスコープが含まれている場合も拒否されます。どのツールからも返されません。より広いスコープを持つ Colab CLI のトークンとは別です。
ツールの範囲	このサーバーが作成したノートブックのフォルダー作成、作成／一覧表示／オープン／保存／ゴミ箱への移動を行います。完全削除、フォルダー削除、共有、権限設定、ほかのファイルの読み取り、自由形式のクエリや ID の指定はできません。テストでは、DELETE リクエストや権限／エクスポート／コピーのエンドポイントが一切使用されないことを検証します。
ファイルの保護（オープン、保存、削除）	ファイルにはこのサーバーのマーカーが付いており、Colab ノートブックで、自分が所有し、アプリフォルダー直下またはそのプロジェクトフォルダー内にあり、ゴミ箱に入っていない必要があります。削除するには、正確な名前を再入力する必要もあります。保存で変更されるのは内容のみです。名前、場所、共有設定は変更されません。
制限と記録	1 時間あたり、ノートブック作成 20 回、プロジェクトフォルダー作成 10 回、保存 60 回、削除 5 回、サインイン試行 6 回です（COLAB_MCP_DRIVE_MAX_CREATES_PER_HOUR、_MAX_PROJECTS_PER_HOUR、_MAX_SAVES_PER_HOUR、_MAX_DELETES_PER_HOUR、_MAX_LOGINS_PER_HOUR）。内容を保存しない追記専用の監査ログ（audit.log、0600）もあります。
コンテンツの衛生管理	ファイルからアップロードしたノートブックでは、出力が削除されます。保存では出力が保持されます（keep_outputs=False にすると無効になります）。アップロードまたは保存する内容に、シークレットファイル内の値が含まれている場合は拒否されます。Drive から読み取った名前は、制御文字と双方向制御文字が取り除かれ、データとしてラベル付けされます。

残存リスクを率直に記載します。「完全に安全」と主張できる人はいません。残るリスクは以下のとおりです。

• プロンプトインジェクションを受けたエージェントや誤った操作をするエージェントでも、（レート制限の範囲内で）不要なノートブックを作成したり、承認を得たうえで このサーバーが作成した ノートブックをゴミ箱に移動したりすることは可能です。ノートブックは Drive のゴミ箱から復元できます。
• 名前の確認は誤操作を防ぐためのものであり、名前を繰り返し入力するモデルを止めるものではありません。実際の制御となるのは、クライアントでの人間による承認プロンプトです。
• ユーザーアカウントのファイルを読み取れる人は、ログアウトするまでトークンを使用できます。ディスクの暗号化とアカウントのロックは、ご自身で行ってください。
• 作成したノートブックには、後で Colab 上でアカウントを使って実行されるコードが含まれる可能性があります。開く内容を確認してください。
• Google の Testing モードでは、外部アプリのリフレッシュトークンは 7 日後に期限切れになるため、毎週再ログインが必要になる場合があります。
• Drive にマウントされた VM 上で実行されるコードが Colab-MCP という名前の Drive フォルダーも作成した場合、Drive 上に同名のフォルダーが 2 つでき、このツールでは別々のフォルダーとして扱われる可能性があります（⚠️ 未検証）。プロジェクトごとにルートを 1 つだけ使用してください。
• Google Drive の実環境では、まだ実行されていません（既知の不明点を参照）。

環境変数：COLAB_MCP_DRIVE（有効化）、COLAB_MCP_DRIVE_COPY_HOURS、COLAB_MCP_DRIVE_DIR（デフォルトは ~/.config/colab-mcp/drive）、COLAB_MCP_DRIVE_CLIENT、COLAB_MCP_DRIVE_TOKEN、COLAB_MCP_DRIVE_AUDIT、COLAB_MCP_DRIVE_FOLDER（デフォルトは Colab-MCP）。

インストール

PyPI からインストール（推奨）

uv が必要です（curl -LsSf https://astral.sh/uv/install.sh | sh）。先に公式の Colab CLI をインストールし、サインインしてください。

uv tool install google-colab-cli
colab sessions        # sign in ONCE (open the link, paste the code)

Claude Code：

claude mcp add colab-cli -e COLAB_MCP_WORKDIR="$HOME/colab-work" -- uvx colab-cli-mcp

Claude Desktop（claude_desktop_config.json。アプリから見つけられない場合は、uvx のフルパスを指定してください。which uvx を参照してください）：

{
  "mcpServers": {
    "colab-cli": {
      "command": "uvx",
      "args": ["colab-cli-mcp"],
      "env": { "COLAB_MCP_WORKDIR": "/Users/YOU/colab-work" }
    }
  }
}

その他の MCP クライアント： stdio サーバーを起動できるクライアントであれば、uvx colab-cli-mcp を実行できます（未テストです。「ステータス」を参照してください）。

省略可能なシークレットファイル（リポジトリの外に置き、自分だけが読み取れるようにしてください）と Drive ツール：

mkdir -p ~/.config/colab-mcp
printf 'OPENROUTER_API_KEY=your-key-here\n' > ~/.config/colab-mcp/secrets.env
chmod 600 ~/.config/colab-mcp/secrets.env

上記のコマンドに -e COLAB_MCP_ENV_FILE="$HOME/.config/colab-mcp/secrets.env" を追加してください（または、JSON の env に同じキーを追加してください）。省略可能な Drive ツールを使うには、-e COLAB_MCP_DRIVE=1 を追加し、Google Drive の説明に従って一度サインインしてください。

使用する人はそれぞれ、自分の Google アカウントを使ってこれらの手順を繰り返してください。サインイントークンは個人のものであり、共有してはいけません。

ソースからインストール（コードを変更する場合）

クローンしたリポジトリで bash install.sh（macOS/Linux）を実行すると、インストール前に確認があり、Colab にサインインしたうえで、Claude Code にサーバーを登録します（または Claude Desktop の設定を表示します）。手動での手順は以下のとおりです。

# 1. uv and the official CLI
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install google-colab-cli

# 2. Sign in ONCE (open the link, paste the code)
colab sessions

# 3. This server
git clone https://github.com/amgallego8/Colab-MCP ~/Colab-MCP

省略可能なシークレットファイル（リポジトリの外に置き、自分だけが読み取れるようにしてください）：

mkdir -p ~/.config/colab-mcp
printf 'OPENROUTER_API_KEY=your-key-here\n' > ~/.config/colab-mcp/secrets.env
chmod 600 ~/.config/colab-mcp/secrets.env

Claude Code に登録する：

claude mcp add colab-cli \
  -e COLAB_MCP_WORKDIR="$HOME/colab-work" \
  -e COLAB_MCP_ENV_FILE="$HOME/.config/colab-mcp/secrets.env" \
  -- uv run --directory ~/Colab-MCP colab-cli-mcp

Claude Desktop に登録する（claude_desktop_config.json）：

{
  "mcpServers": {
    "colab-cli": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/YOU/Colab-MCP", "colab-cli-mcp"],
      "env": {
        "COLAB_MCP_WORKDIR": "/Users/YOU/colab-work",
        "COLAB_MCP_ENV_FILE": "/Users/YOU/.config/colab-mcp/secrets.env"
      }
    }
  }
}

使用する人はそれぞれ、自分の Google アカウントを使ってこれらの手順を繰り返してください。サインイントークンは個人のものであり、共有してはいけません。

環境変数

変数	デフォルト	用途
COLAB_MCP_WORKDIR	現在のディレクトリ	サーバーが操作する唯一のローカルフォルダー
COLAB_MCP_ENV_FILE	—	シークレットを含む NAME=value 形式のファイル
COLAB_MCP_AUTH	CLI のデフォルト	oauth2 または adc（CLI の --auth）
COLAB_MCP_MAX_OUTPUT	20000	1 回の呼び出しで返される最大文字数
COLAB_MCP_MAX_UPLOAD_MB	100	ファイル／ZIP のアップロード上限（CLI はファイルを 1 回のリクエストで送信します）
COLAB_MCP_MAX_DOWNLOAD_MB	1024	展開後のディレクトリダウンロードの上限
COLAB_BIN	colab	CLI 実行ファイルのパス
COLAB_MCP_MIN_FREE_GB	5	ダウンロード後に残しておく必要がある空きディスク容量
COLAB_MCP_WORKDIR_MAX_GB	20	作業フォルダーの容量上限（0 = 上限なし）
COLAB_MCP_IMAGE_DAYS / COLAB_MCP_TRASH_DAYS / COLAB_MCP_DRIVE_COPY_HOURS	2 / 7 / 24	保存したプロット、ローカルでゴミ箱に移動したノートブック、Drive の作業用コピーを削除するまでの期間（0 = ゴミ箱／コピーを保持）
COLAB_MCP_DRIVE_PROJECTS	Colab-MCP	Drive が VM にマウントされている場合に、ファイルツールが使用できる唯一の Drive フォルダー（MyDrive の下）

ノートブックの仕組み

ノートブックは、作業ディレクトリ内にある通常の .ipynb ファイルです。nbformat を使ってローカルで編集するため、編集にランタイムは必要ありません。colab_notebook_run_cell は colab exec を通じて 1 つのセルをランタイムに送信します。カーネルは呼び出しの間も変数を保持し、セルの出力（テキスト、エラー、表示されたプロット）はノートブックに書き戻されます。セルは id（安定）またはインデックスで指定します。プロットは .colab-mcp/images/ に保存されます。

.ipynb ファイルを指定して colab_exec を実行すると、ノートブック全体が実行され、CLI はその隣に <name>_output.ipynb を保存します。

既知の未確認事項（実際の Colab で確認が必要）

これらは CLI のソースとドキュメントを読んで確認した事項です。「ステータス」で説明した実際の実行では検証していません。

• exec 呼び出しの間でカーネル変数が保持されるか（ソースでは同じカーネル ID を再利用しているため、保持されるはずです）。
• セルの成功／失敗の検出が、Colab カーネルで get_ipython().run_cell を利用できることに依存している点。
• --output-image があらゆる形式の画像を保存するか（PNG／JPEG の表示データには対応しています）。
• 実際のアップロードサイズ上限（CLI はファイルを単一のリクエストで送信します。100 MB という上限は保守的な推測です）。
• CLI 経由で実行した際に、カーネルから Colab の Secrets（userdata）を読み取れるかどうか（ドキュメントに記載がありません。代わりに secrets=[...] を使用してください）。
• Google Drive（オプトイン。後述）：Colab の MIME タイプ application/vnd.google.colaboratory は、Google の Drive ドキュメントで見つかりませんでした。サーバーは作成後に Drive に保存された内容を確認し、異なっていれば取り消しますが、実際の Drive ではまだ実行していません。
• 未確認のままの Google Cloud アプリを、所有者が「Testing」モードのリフレッシュトークン有効期限である 7 日を超えて使用できるかどうか（Google のドキュメントによると、「Testing」モードの外部アプリのリフレッシュトークンは 7 日で期限切れになりますが、「In production」状態の未確認アプリに関するルールは確認できていません）。

開発

pip install "mcp<2" nbformat google-auth google-auth-oauthlib requests
python tests/test_server.py   # the Colab tools, with a simulated CLI
python tests/test_drive.py    # the Drive tools, with a simulated Drive API
python tests/test_footprint.py # local cleanup and disk guards
python tests/test_mount.py     # Drive mount from the chat, with a simulated CLI

SDK のバージョンを mcp<2 に固定しているのは意図的です。2.x では FastMCP の名前が MCPServer に変更されました。

利用規約とプライバシー

TERMS.md をご覧ください。サーバーやメンテナーによるデータ収集がないこと、ローカルに保存されるデータ、ユーザーの責任、サインイン方法ごとに Google への問い合わせに対応する人、保証に関する免責条項について説明しています。

ライセンス

Apache License 2.0 — LICENSE をご覧ください。著作権は Colab-MCP のコントリビューター（amgallego8）に帰属します（2026 年）。このプロジェクトがラップする Google の公式 Colab CLI は別の著作物で、こちらも Apache-2.0 ライセンスですが、本プロジェクトには含まれていません。

---

スペイン語の概要

エージェントが Google Colab を最初から最後まで利用できる MCP サーバーです。GPU／TPU ランタイムの作成と停止、コードの実行、ノートブックでのセル単位の作業、長時間ジョブのバックグラウンド実行、VM との間でのファイルやフォルダーの転送ができます。Google の 公式 Colab CLI をラップしています。

• ステータス： モック CLI でテスト済み（292 件のチェック：118 + 129 + 28 + 17）。実際の Colab セッションで 1 回、実環境で検証済み（macOS と Claude）：ランタイムの作成、コードの実行、ログ付きの長時間ジョブ、チャットからの Drive のマウント。「Known unknowns」を参照してください。実環境で未検証： drive_* ツール、セル単位のノートブック操作、フォルダー、その他のクライアント。
• セキュリティ： ローカルパスは COLAB_MCP_WORKDIR 内に制限されます。キーはローカルファイルに保存され、モデルに返されません。シェルはありません。ノートブックの削除は復元可能なゴミ箱に移動されます。
• インストール： PyPI から uvx colab-cli-mcp を使用するか、install.sh でソースからインストールします。各ユーザーは、自分の Google アカウントを使って「Install」の手順を繰り返す必要があります。セッショントークンは個人用です。
• Google Drive（オプション）： Drive の Colab-MCP/<proyecto>/ にプロジェクトフォルダーと Colab ノートブックを作成、開く、保存、ゴミ箱に移動できます。それ以外の操作は行いません。Google クライアントは各ユーザーが一度だけ作成します（共有クライアントはまだ公開されていません）。その後、必要に応じてサーバーがブラウザーを開くので、「許可」をクリックするだけです（コードとトークンがチャットを経由することはありません）。権限は drive.file で、このツールが作成したものだけを参照できます。コンピューターにはほとんど何も残りません。一時ファイルは自動的に削除され、大きなファイルは VM のディスクまたは Drive に保存されます。エージェントの操作をこれらの機能に限定するスキル（skills/colab-drive-notebooks）があります。「Google Drive」と脅威モデル、および残存リスクをご覧ください。実際の Drive API ではまだテストしていません。
• 費用： 実行する処理には、Colab のコンピューティングユニットが消費されます。使用していないセッションは停止してください。