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 ツール

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

Related MCP server: mcp-colab-gpu

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