Skip to main content
Glama
google-colab

google-colab

by etrnya
README.md
# ⚡ 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 跑完即關機。

🌐 **語言切換**:[繁體中文](README.md) | [English](README_EN.md)

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Managed_Colab_Endpoint-4285F4.svg)](https://developers.google.com/colab/api/reference/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` 一次解決以上所有問題!**

---

## 🏗️ 架構總覽

```mermaid
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):**
```powershell
git clone https://github.com/etrnya/colab-mcp-starter.git
cd colab-mcp-starter
.\scripts\setup_env.ps1
```

**macOS / Linux:**
```bash
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`,或在終端執行:
  ```powershell
  .\.venv\Scripts\colab.exe sessions
  ```
* **macOS / Linux**:
  ```bash
  .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 消耗)

```powershell
.\.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(執行完自動關機)

```powershell
.\.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 驗證)*

實測輸出範例:
```text
[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_config.example.json) 並將路徑改為您本機的實際路徑,貼入您的 MCP Host 設定檔:

```json
{
  "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 確認裝置並回報,最後**只刪掉這次開的執行環境**。」

---

## 📚 進階文件

* 🛠️ [實戰踩坑與排雷指南 (docs/TROUBLESHOOTING.md)](docs/TROUBLESHOOTING.md)
* 💡 [36 個高落地 Colab GPU + MCP 實作場景 (docs/USE_CASES_36.md)](docs/USE_CASES_36.md)
* 🧭 [開發與架構指南 (DEVELOPMENT_GUIDE.md)](DEVELOPMENT_GUIDE.md)
* 📖 [術語字典 (GLOSSARY.md)](GLOSSARY.md)

## 🧪 離線單元測試

```powershell
python -m unittest discover -s tests -v
```

## 🔗 官方參考資料

* [Google Colab API & MCP 團隊公告](https://medium.com/google-colab/the-google-colab-api-and-mcp-endpoint-for-developers-and-agents-65cfef497056)
* [Google Colab Official MCP Reference](https://developers.google.com/colab/api/reference/mcp)
* [googlecolab/google-colab-cli](https://github.com/googlecolab/google-colab-cli)
* [Colab FAQ](https://research.google.com/colaboratory/faq.html?hl=en)

## 📜 授權協議

Copyright © 2026 `etrnya`.  
本專案採用 **[Apache License 2.0](LICENSE)** 授權條款釋出。