Skip to main content
Glama
google-colab

google-colab

by etrnya

⚡ colab-mcp-starter

5 分鐘打通 Google Colab CLI 雲端 GPU POC + 官方代管 Colab MCP (https://colaboratory.googleapis.com/mcp)!
內建零明文憑證本機 Stdio Bridge,讓 Antigravity、Claude Code、Claude Desktop、Cursor 免手動貼 Token、自動續期 OAuth,直接向 Google Colab 借一張 T4 / L4 / A100 GPU 跑完即關機。

🌐 語言切換:繁體中文 | English

License Python MCP


🎯 為什麼做這個專案?

Google 推出 Colab API 與官方代管 MCP Endpoint 後,AI 助理已經可以直接透過 MCP 開啟 Colab GPU、執行 Python 並關機釋放額度。但實務上開發者常卡在三個痛點:

  1. Token 過期與外洩風險:Google OAuth Access Token 約 1 小時就過期,直接寫死在 mcp_config.json 不僅每小時失效,還有明文外洩風險。

  2. Windows 安裝踩坑:沒有 uv 時直接 pip install 容易漏掉 Google 分支版 jupyter-kernel-client,或在終端按 Ctrl+C 複製網址時把 OAuth 登入中斷。

  3. 怕忘記關機空燒 CU:需要一套標準「開機 → 運算 → 自動刪除 Runtime」的最小範本。

colab-mcp-starter 一次解決以上所有問題!


Related MCP server: mcp-server-colab-exec

🏗️ 架構總覽

graph LR
    A["AI 助理 / MCP Host<br/>(Antigravity / Claude / Cursor)"] -->|stdio JSON-RPC 2.0| B["colab_mcp_starter<br/>mcp_stdio_bridge.py"]
    B -->|讀取加密憑證 & 自動續期| C["OS Keyring<br/>(Windows Credential Manager / Keychain)"]
    B -->|HTTPS + Bearer Token| D["Google 官方代管 MCP<br/>https://colaboratory.googleapis.com/mcp"]
    D -->|create_runtime / execute_code / delete_runtime| E["Google Colab 雲端 GPU<br/>(T4 / L4 / A100 / TPU)"]
  • Zero-Leak Invariant:mcp_config.json 中零明文 Token,OAuth 憑證全程留在作業系統加密鑰匙圈並由 colab_cli.auth.get_credentials() 自動續期。

  • 預付封頂零帳單暴衝:直接複用 Google AI Plus / Pro / Ultra 訂閱內含的 Compute Units (CU),不會有雲端後付 API 的天價帳單風險。


🚀 5 分鐘快速接通指南

Step 1:安裝環境(建立隔離 .venv)

Windows (PowerShell):

git clone https://github.com/etrnya/colab-mcp-starter.git
cd colab-mcp-starter
.\scripts\setup_env.ps1

macOS / Linux:

git clone https://github.com/etrnya/colab-mcp-starter.git
cd colab-mcp-starter
chmod +x scripts/setup_env.sh && ./scripts/setup_env.sh

Step 2:完成一次 Google OAuth 授權

  • Windows:雙擊 scripts\login_colab.bat,或在終端執行:

    .\.venv\Scripts\colab.exe sessions
  • macOS / Linux:

    .venv/bin/colab sessions

⚠️ 防坑提醒:終端顯示 https://accounts.google.com/o/oauth2/auth?... 時,千萬不要按 Ctrl + C(會中斷程式)!請用 Ctrl + 滑鼠左鍵點擊 開啟網址,登入 Google 帳號後將授權碼貼回 Enter the authorization code: 按 Enter。

完成後,執行 .\.venv\Scripts\colab.exe usage 即可看到您帳號目前的 Compute Units (CU) 餘額。


Step 3:驗證官方代管 Colab MCP(0 CU 消耗)

.\.venv\Scripts\python.exe examples\verify_mcp_endpoint.py

成功輸出會列出官方 Colab MCP 暴露的全部 10 個工具:

工具分類

官方 MCP 工具名稱

規格與訂閱

list_runtime_specs、get_subscription

環境生命週期

create_runtime、get_runtime、list_runtimes、delete_runtime

Kernel 與執行

create_session、list_sessions、delete_session、execute_code


Step 4:跑通第一個最小 GPU POC(執行完自動關機)

.\.venv\Scripts\colab.exe run --gpu T4 examples\poc_gpu_check.py

(若當下 T4 無可用容量,去掉 --gpu T4 改跑 .\.venv\Scripts\colab.exe run examples\poc_gpu_check.py 即可用 CPU 驗證)

實測輸出範例:

[colab] Creating session 'run-d59607'...
[colab] Session READY (run-d59607). Executing poc_gpu_check.py...
=== Google Colab Runtime POC Check ===
Python   : 3.13.16
GPU      : Tesla T4 (14.6 GB VRAM)
CUDA Op  : OK (2048x2048 matmul mean=-0.013331)
=== POC Complete (colab run will auto-terminate this runtime) ===
[colab] Stopping session 'run-d59607'...
[colab] Session terminated.

Step 5:掛載到 Antigravity / Claude / Cursor(零明文 Token)

複製 mcp_config.example.json 並將路徑改為您本機的實際路徑,貼入您的 MCP Host 設定檔:

{
  "mcpServers": {
    "google-colab": {
      "command": "C:/path/to/colab-mcp-starter/.venv/Scripts/python.exe",
      "args": [
        "-m",
        "colab_mcp_starter.mcp_stdio_bridge"
      ],
      "env": {
        "PYTHONPATH": "C:/path/to/colab-mcp-starter/src"
      }
    }
  }
}

(macOS / Linux 請將 command 改為 /path/to/colab-mcp-starter/.venv/bin/python)

掛載完成後,就可以直接對 AI 助理說:

「先查我帳號目前能開的 Colab 規格,挑一個可用的 GPU 開環境,執行一段 PyTorch 確認裝置並回報,最後只刪掉這次開的執行環境。」


📚 進階文件

🧪 離線單元測試

python -m unittest discover -s tests -v

🔗 官方參考資料

📜 授權協議

Copyright © 2026 etrnya.
本專案採用 Apache License 2.0 授權條款釋出。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible AI assistants to run Python code on Google Colab GPU/TPU runtimes, supporting accelerators like T4, A100, H100, with background execution and Google Drive integration.
      10
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that allocates Google Colab GPU runtimes (T4/L4) and executes Python code on them. Lets any MCP-compatible AI assistant run GPU-accelerated code without local GPU hardware.
      3
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to execute Python code on Google Colab GPU/TPU runtimes via the official Colab CLI, with session, file, and package management capabilities.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Lets any MCP-compatible agent use Google Colab or Jupyter runtimes as an execution backend, enabling code execution, notebook management, package installation, hardware introspection, training jobs, and file handling.
      40
      1
      MIT