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)	colab install	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)	colab drivemount	Google Drive マウント
session_log(session, lines, event_type)	colab log	実行履歴
session_notebook_url(session)	colab url	同じ VM にブラウザから接続する URL
cli_version()	colab version	CLI バージョン

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 a24.be8a@g.chuo-u.ac.jp

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 colab-cli-mcp sh -c "colab 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

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