colab-cli-mcp

Google 公式の google-colab-cli をラップした リモート MCP サーバーです。ブラウザ・ws://localhost・SSH トンネルを一切使わずに、 Notion AI などの MCP クライアントから Colab の GPU/TPU ランタイムで Python を実行できます。

Notion AI ──HTTPS(OAuth)──▶ colab-cli-mcp ──subprocess──▶ colab CLI ──HTTPS──▶ Colab runtime

MCP ツール

ツール	対応する CLI	説明
create_session(session, gpu, tpu)	colab new	ランタイム作成（gpu: T4/L4/G4/H100/A100、tpu: v5e1/v6e1、無指定は CPU）
list_sessions()	colab sessions	セッション一覧（runtime token は返しません）
session_status(session)	colab status	状態確認
stop_session(session)	colab stop	ランタイム解放
restart_kernel(session)	colab restart-kernel	カーネル再起動
run_code(code, session, timeout)	colab exec -f	Python コード実行
install_packages(packages, session, timeout)	colab exec	uv / pip でパッケージ導入
list_files(path, session)	colab ls	VM 上のファイル一覧
read_remote_file(remote_path)	colab download	VM 上のテキストを取得
write_remote_file(remote_path, content)	colab upload	VM 上にテキストを書き込み
download_to_workspace / upload_workspace_file	colab download / upload	大きい/バイナリファイル用
remove_remote_file(path, session)	colab rm	ファイル削除
mount_drive(path, session, force_remount)	colab exec	Google Drive マウント
session_log(session, lines, event_type)	colab log	実行履歴
session_notebook_url(session)	colab url	同じ VM にブラウザから接続する URL
cli_version()	colab version	CLI バージョン

実装メモ: install_packages と mount_drive は colab exec 経路で実行しています。 colab install / colab drivemount 自体は正常に動作しますが、colab-cli 0.6.0 の run_automation() には colab exec が持っているセッション存在チェック (if not s) がなく、セッションがローカル状態から消えていると AttributeError: 'NoneType' object has no attribute 'url' という生のトレースバックを返します。 exec 経路にそろえることで、エラー処理を統一し、タイムアウト指定と 完了マーカーによる成否判定を可能にしています。

Google Drive のマウントについて: Drive の認可が未取得の場合、 どちらの方式でもヘッドレスでは完結しません。colab drivemount の認証フックは open("/dev/tty") での手動確認を要求するため、TTY のないコンテナでは 600 秒のタイムアウトまでハングします。exec 経路なら timeout 秒で 打ち切って原因を含むエラーを返します。初回は session_notebook_url の URL を ブラウザで開き、Drive アクセスを一度許可してください。

repl / console / edit / ssh / pay / update は対話専用なので意図的に除外しています。

2 層の認証

1. MCP クライアント → 本サーバー: --auth token|none|google|github|oidc
2. 本サーバー → Colab: Colab CLI 自身の --colab-auth oauth2|adc

1. MCP 側（Notion AI から繋ぐ）

colab-cli-mcp \
  --transport http --host 0.0.0.0 --port 8080 --path /mcp \
  --auth google \
  --base-url https://colab-mcp.example.com \
  --oauth-client-id  xxxxx.apps.googleusercontent.com \
  --oauth-client-secret GOCSPX-xxxxx \
  --allowed-identity you@example.com

Google Cloud Console のリダイレクト URI には <base-url>/auth/callback を登録します。 公開が必要なエンドポイント: /mcp, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource/mcp, /authorize, /token, /register, /consent, /auth/callback。

警告: --allowed-identity を省略すると、OAuth を通った 任意の Google アカウントが あなたの Colab で任意コードを実行できます。必ず自分のアドレス（または @domain）を指定してください。

2. Colab CLI 側（ヘッドレスサーバーでの初回認証）

CLI はブラウザなしでも認証できます（auth.py の remote flow / token_usage=remote）。 サーバー上で 1 回だけ手で実行してトークンを作ります。

# コンテナ内で 1 回だけ
docker compose run --rm --entrypoint colab colab-cli-mcp sessions
#   → 表示された URL を手元のブラウザで開き、
#     表示された認可コードを貼り付ける（~/.config/colab-cli/token.json に保存）

ADC を使う場合は --colab-auth adc にして、

gcloud auth application-default login \
  --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratory

~/.config/colab-cli/ と workspace は 必ず volume で永続化してください（compose 済み）。

Docker

GHCR の公式イメージを使う（ビルド不要）

main への push ごとに GitHub Actions が linux/amd64 + linux/arm64 の マルチアーキイメージを自動で公開しています。

docker pull ghcr.io/animationsaver/colab-cli-mcp:latest

タグ: latest / main / sha-<short> / リリース時は 1.2.3・1.2。

cp .env.example .env
# .env を編集（最低限 COLAB_CLI_MCP_AUTH_TOKEN を openssl rand -hex 24 で埋める）
docker compose -f docker-compose.ghcr.yml up -d

# 初回のみ: Colab CLI の認証（トークンは volume に残るので 1 回だけ）
docker compose -f docker-compose.ghcr.yml run --rm --entrypoint colab colab-cli-mcp sessions

動作確認:

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer $COLAB_CLI_MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

イメージを更新するときは docker compose -f docker-compose.ghcr.yml pull && \ docker compose -f docker-compose.ghcr.yml up -d。

ソースからビルドする

export COLAB_CLI_MCP_BASE_URL=https://colab-mcp.example.com
export COLAB_CLI_MCP_OAUTH_CLIENT_ID=...
export COLAB_CLI_MCP_OAUTH_CLIENT_SECRET=...
export COLAB_CLI_MCP_ALLOWED_IDENTITY=you@example.com
docker compose up -d --build

TLS は Caddy / nginx / Cloudflare Tunnel などで前段終端してください。

環境変数

COLAB_CLI_MCP_ + TRANSPORT / HOST / PORT / PATH / AUTH / AUTH_TOKEN(csv) / BASE_URL / OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET / OAUTH_SCOPE(csv) / OAUTH_REDIRECT_PATH / OAUTH_NO_CONSENT / OIDC_CONFIG_URL / ALLOWED_IDENTITY(csv) / EXECUTABLE / COLAB_AUTH / COLAB_OAUTH_CONFIG / COLAB_STATE / WORKSPACE

設計上のポイント

• ローカル FS のサンドボックス: upload/download のローカル側は workspace 配下に限定（.. は拒否）。
• セッション単位のロック: Colab カーネルは同時 1 リクエストなので asyncio.Lock で直列化。
• 秘密情報の非公開: sessions.json の token（runtime proxy token）はツール出力から除去。
• 出力の正規化: rich の枠線・ANSI・アップデートバナーを除去してから返す。
• 既知の上流バグ: 長時間実行は google-colab-cli#14 （80 秒で無応答）の影響を受ける可能性があります。run_code の timeout は余裕を持たせてください。

開発

uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest -q

Multiple Google accounts

Every account gets its own HOME under <workspace>/accounts/<name>/, so its token.json, sessions.json, settings.json and history stay separate. The default account keeps the container HOME (~/.config/colab-cli), so an already authenticated deployment keeps working with no migration.

Tool	Purpose
list_accounts	Show configured accounts, which one is active, and their sessions
switch_account	Make an account active for every later call (creates it if new)
authorize_account	Sign an account in: first call returns the Google URL, second call takes the code
forget_account	Delete a named account credentials, sessions and history

Sign in a second account without a terminal:

1. switch_account { "account": "work" }
2. authorize_account {} -> returns authorization_url
3. Open the URL, approve, copy the code Google shows
4. authorize_account { "code": "4/0A..." } -> signed_in: true

Google はコードを「その URL を発行したサインインフロー」に紐付けるため、URL を表示した CLI プロセスはプロンプトで待機したまま保持され、2 回目の呼び出しが同じプロセスへコードを入力 します。待機は 15 分（PENDING_PROMPT_TTL）で失効するので、過ぎた場合は 2. からやり直して ください。

Start the server on a given account with --colab-account NAME or COLAB_CLI_MCP_COLAB_ACCOUNT=NAME.

Google allows one Colab runtime assignment per account, so separate accounts are also the way to run more than one runtime at a time.

Session lifetime and the keep-alive daemon

colab new starts a detached keep-alive process (colab keep-alive, recorded as keep_alive_pid) that pings /tun/m/<endpoint>/keep-alive/ every 60 seconds. It is detached from any terminal, so closing the shell does not end the session - but it lives inside this container, so docker compose down, a restart or an image update kills it, and Colab then idles the runtime out.

The daemon also stops on its own after 24 hours (time_limit_reached), when the local session record disappears (session_not_found), when the endpoint changes (endpoint_mismatch), or after two consecutive 4xx replies (consecutive_4xx_errors, usually a missing colaboratory OAuth scope). Check session_log for the keep_alive_stopped event and its reason.