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://www.python.org/)
[](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)** 授權條款釋出。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues