Google Colab API与MCP Endpoint教程:Claude Code调用云GPU
详解Google于2026年11月17日正式发布的Google Colab API与官方托管MCP Endpoint(https://www.google.com/search?q=colaboratory.googleapis.com/mcp):手把手教你让Claude Code、Gemini CLI与Cursor直接拉起Colab免费T4或付费H100/TPU v6e执行代码,附Colab CLI对比与Codex接入Vertex AI指南。
目录 · 18 节
- Google Colab API 与 MCP Endpoint 实战教程:在 Claude Code 与 Gemini CLI 中直接调用云端 H100 与 TPU
- 一、本教程能帮你做到什么与三大工具(API / MCP / CLI)选型对比
- 前置条件与费用说明
- 二、分步骤操作:配置 Colab MCP Endpoint 与 REST API 实战
- 步骤 1:在 Google Cloud Console 开启服务并认识 10 大 MCP 工具
- 步骤 2:完整代码示例(cURL 调 MCP / Python 调 REST API / Colab CLI 对照)
- 步骤 3(加餐):将 OpenAI Codex CLI 与桌面端直接接入 Google Cloud Vertex AI
- 三、常见报错和解决方法(Troubleshooting)
- 报错 1:让 Agent 在 execute_code 中用 matplotlib 画了 Loss 曲线图或保存了 .pt 模型权重,但 MCP 返回结果里只有文字没有图片/文件
- 报错 2:调用 create_runtime 申请 H100 或 TPU v6e 时返回权限拒绝或资源不可用
- 报错 3:只调用了 delete_session,以为云端 GPU 已经停止计费了
- 四、费用估算与使用建议
- 五、总结
- 常见问题
- 1. Google Colab API 和 MCP Endpoint 需要付费订阅 Colab Pro 才能用吗?
- 2. 我已经在 Claude Code 里用熟了今年 6 月发布的 Colab CLI,有必要全部迁移到新的 Colab MCP Endpoint 吗?
- 3. 在 Google Cloud Vertex AI 中接入 OpenAI Codex CLI 目前支持调用哪些模型?
- 参考来源
Google Colab API 与 MCP Endpoint 实战教程:在 Claude Code 与 Gemini CLI 中直接调用云端 H100 与 TPU
当你在本地轻薄本上运行 Claude Code、Gemini CLI、Cursor 或 OpenAI Codex 时,最痛苦的瓶颈往往不是模型不够聪明,而是本地没有大显存 NVIDIA GPU——每当 Agent 写完一段 PyTorch 微调脚本、CUDA 算子或大规模数据清洗代码,你都不得不手动把代码复制粘贴到浏览器的 Google Colab 笔记本里点运行,再把报错日志复制回终端让 Agent 修改。
2026 年 11 月 17 日,Google 正式发布了 「Google Colab API」 与官方托管的 「Google Colab MCP Endpoint」(https://colaboratory.googleapis.com/mcp),并且宣布向包括免费版(Free Tier)在内的所有 Colab 用户全面开放(npaka 深度技术解析)。这意味着,从今天起,你的本地 AI 编程 Agent 无需打开任何浏览器,就能直接通过标准 Model Context Protocol(MCP)按需在云端创建 T4 / H100 GPU 或 TPU v6e 运行时、保持有状态的 Python 会话执行代码、读取训练输出,并在任务完成后自动销毁实例!同日,Google Cloud 还正式上线了将 OpenAI Codex CLI 与桌面端直接接入 Google Cloud Vertex AI 的官方指南(Google Cloud 官方文档)。本教程将手把手带你跑通这两套云端算力挂载方案。
一、本教程能帮你做到什么与三大工具(API / MCP / CLI)选型对比
通过本教程(预计操作时间 20 分钟),你将掌握:
- 在 Google Cloud Console 中启用 Colab API 并配置 OAuth 2.0 凭据。
- 将官方托管的
https://colaboratory.googleapis.com/mcp接入 Claude Code 或 Gemini CLI,让 Agent 自动调用create_runtime、create_session与execute_code等 10 个核心工具在云端 GPU 上训练模型。 - 厘清 Colab API、Colab MCP Endpoint 与今年 6 月发布的 Colab CLI 的差异,并附带将 OpenAI Codex 接入 Google Cloud Vertex AI 的完整配置。
前置条件与费用说明
- 账号要求:拥有普通 Google 账号及关联的 Google Cloud Project(用于申请 OAuth 2.0 客户端凭据)。
- 费用说明(以官方最新公布为准):Colab API 与 MCP Endpoint 本身对所有用户(含 Colab 免费层)免费开放!底层硬件资源(CPU、T4 GPU、H100 GPU、TPU v6e)则严格遵循你当前账号的 Colab 订阅计划(Free / Pro / Pro+ / Pay As You Go)与计算单元(Compute Units)配额限制。
在动手配置前,请先通过下表判断你的场景最适合使用 Google 提供的哪一种无头(Headless)操控方式(核实自 npaka 技术总结):
| 对比维度 | Google Colab MCP Endpoint(2026-11-17 新增) | Google Colab REST API(2026-11-17 新增) | Google Colab CLI(2026-06 发布) |
|---|---|---|---|
| 核心交互方式 | AI Agent 直接通过标准 MCP 协议调用 create_runtime、execute_code 等 10 个工具 |
外部后端程序通过 HTTP REST(OpenAPI 3.0)管理运行时,配合 Jupyter Server 执行代码 | 开发者或终端 Agent 在本地 Shell 中执行 colab run --gpu T4 train.py 等命令 |
| 最佳适用场景 | Claude Code、Gemini CLI、Cursor 等原生支持 MCP 的智能体交互式实验与调试 | 将 Colab 云端 GPU 调度能力嵌入你自研的 Python/Web SaaS 应用或 VS Code 插件后台 | 习惯纯命令行脚本、需要快速同步本地 .py 文件并导出 .ipynb 日志的终端工作流 |
| 状态保持与文件返回 | 同一 session 内保持 Python 变量与已加载库状态;注意:execute_code 直接返回纯文本 stdout/stderr,图片或大文件需走独立 HTTP 连接拉取 |
完全编程可控(Google 官方“Colab for VS Code”插件底层正是基于此 API) | 原生支持 -f 上传本地脚本与 colab log --output 导出完整笔记本文件 |
二、分步骤操作:配置 Colab MCP Endpoint 与 REST API 实战
步骤 1:在 Google Cloud Console 开启服务并认识 10 大 MCP 工具
无论你是使用 REST API 还是 MCP Endpoint,都需要在 Google Cloud Console 中完成一次性的前置授权(npaka 指南):
- 打开 Google Cloud Console,选择或新建一个项目(Project)。
- 在「API 和服务(APIs & Services)」库中搜索并启用 Google Colab API(如果使用 MCP,同步开启对应的 MCP Server 开关)。
- 进入「凭据(Credentials)」,创建 OAuth 2.0 客户端 ID 并完成本地授权登录,获取有效的 OAuth Access Token。
挂载 https://colaboratory.googleapis.com/mcp 后,你的 AI Agent 将立即获得以下 10 个官方标准 MCP 工具:
- 硬件与订阅查询:
get_subscription:查询当前账号的 Colab 订阅等级(Free / Pro / Pro+)与可用配额。list_runtime_specs:查询当前账号有资格申请的 CPU、GPU(如 T4、L4、A100、H100)及 TPU(如 TPU v6e)硬件规格清单。
- 运行时生命周期管理:
create_runtime:在云端创建一个指定硬件规格(CPU/GPU/TPU)的执行环境。list_runtimes:列出当前账号下所有正在运行的云端环境。get_runtime:获取指定运行时的详细状态与 Jupyter 连接鉴权信息。delete_runtime:(省钱关键!) 任务结束后彻底销毁并释放云端 GPU/TPU 运行时。
- 有状态 Python 会话与代码执行:
create_session:在已创建的 Runtime 上开启一个持久化的 Python 内核会话。list_sessions:列出当前活跃的 Python 会话。execute_code:在指定会话中执行 Python 代码并返回stdout/stderr文本结果(同一 Session 内的全局变量、已导入的 PyTorch 模型与显存张量在多次execute_code调用间完全保留!)。delete_session:终止指定的 Python 会话释放显存。
步骤 2:完整代码示例(cURL 调 MCP / Python 调 REST API / Colab CLI 对照)
写法 A:使用 cURL 直接向 Colab MCP Endpoint 发起 JSON-RPC 工具调用
当你拿到 OAuth 2.0 Bearer Token 后,可以直接用 cURL 验证 https://colaboratory.googleapis.com/mcp 的工具列表与 GPU 代码执行:
# 1. 调用 Colab MCP Endpoint 查询当前可用的 GPU/TPU 硬件规格 (list_runtime_specs)
curl -X POST "https://colaboratory.googleapis.com/mcp" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_runtime_specs",
"arguments": {}
}
}'
# 2. 在已创建的 GPU 会话上通过 execute_code 跑 PyTorch 显存与算力自检
curl -X POST "https://colaboratory.googleapis.com/mcp" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "execute_code",
"arguments": {
"runtime_id": "rt-colab-gpu-01",
"session_id": "sess-pytorch-01",
"code": "import torch\nprint(\"CUDA Available:\", torch.cuda.is_available())\nif torch.cuda.is_available():\n print(\"Device:\", torch.cuda.get_device_name(0))"
}
}
}'
写法 B:使用 Python 封装 Colab MCP / API 自动创建 GPU、训练并自动销毁(防忘关机爆表)
在生产或自动化实验中,最怕 Agent 创建了 H100 运行时却因代码抛异常退出,导致云端 GPU 空转烧光所有 Compute Units。以下 Python 脚本(依赖 httpx>=0.27.0)利用 try...finally 上下文确保无论训练成功还是失败,都会强制调用 delete_runtime 释放算力:
import os
import httpx
# 依赖版本:Python 3.10+, pip install "httpx>=0.27.0"
MCP_ENDPOINT = "https://colaboratory.googleapis.com/mcp"
OAUTH_TOKEN = os.environ["COLAB_OAUTH_ACCESS_TOKEN"]
def call_colab_mcp_tool(client: httpx.Client, tool_name: str, arguments: dict, req_id: int = 1) -> dict:
payload = {
"jsonrpc": "2.0",
"id": req_id,
"method": "tools/call",
"params": {"name": tool_name, "arguments": arguments},
}
resp = client.post(
MCP_ENDPOINT,
headers={"Authorization": f"Bearer {OAUTH_TOKEN}", "Content-Type": "application/json"},
json=payload,
)
resp.raise_for_status()
return resp.json()
def run_remote_gpu_experiment(training_code: str, accelerator: str = "T4"):
with httpx.Client(timeout=120.0) as client:
# 1. 创建云端 GPU 运行时
print(f"🚀 正在申请 Google Colab {accelerator} GPU 运行时...")
rt_res = call_colab_mcp_tool(client, "create_runtime", {"accelerator": accelerator}, req_id=1)
runtime_id = rt_res.get("result", {}).get("runtime_id", "rt-demo")
try:
# 2. 创建持久化 Python Session
sess_res = call_colab_mcp_tool(client, "create_session", {"runtime_id": runtime_id}, req_id=2)
session_id = sess_res.get("result", {}).get("session_id", "sess-demo")
# 3. 执行训练代码并获取 stdout/stderr 文本结果
print("⚡ 正在云端 GPU 上执行训练脚本...")
exec_res = call_colab_mcp_tool(
client,
"execute_code",
{"runtime_id": runtime_id, "session_id": session_id, "code": training_code},
req_id=3,
)
print("📊 云端执行输出:\n", exec_res.get("result"))
finally:
# 4. 铁律:无论成功还是异常,必须在 finally 中销毁 Runtime 防止计算单元空转耗尽!
print(f"🧹 正在销毁云端运行时 {runtime_id} 以释放配额...")
call_colab_mcp_tool(client, "delete_runtime", {"runtime_id": runtime_id}, req_id=4)
if __name__ == "__main__":
sample_code = "import torch; x = torch.randn(4096, 4096, device='cuda'); print((x @ x).norm().item())"
print("Ready to dispatch code to Google Colab MCP Endpoint.")
写法 C:如果你已经在用 Claude Code 终端,直接搭配 Colab CLI 同样极速
正如 npaka 在对比测试中指出的,如果你使用的是本身就具备强大本地 Bash 执行能力的 Claude Code 或 Codex CLI,Google 在 2026 年 6 月发布的 Colab CLI 依然是传文件与保存 .ipynb 最顺手的利器,两者可以互补使用:
# 分步模式:创建 T4 运行时 -> 安装依赖 -> 跑本地脚本 -> 导出完整带图表的 .ipynb 日志 -> 关机
colab new --gpu T4
colab install transformers datasets peft
colab exec -f train.py
colab log --output train_log.ipynb
colab stop
# 或者一条命令全自动完成“开机 -> 运行 -> 关机”闭环:
colab run --gpu T4 train.py
步骤 3(加餐):将 OpenAI Codex CLI 与桌面端直接接入 Google Cloud Vertex AI
除了让 Agent 调用 Colab 算力,Google Cloud 于 11 月 17 日还更新了 Gemini Enterprise Agent Platform 文档,正式支持将 OpenAI Codex CLI 与 Codex Desktop App 直接绑定到你的 Google Cloud 项目账单下调用 OpenAI 合作模型(gpt-6.1-sol、gpt-6-luna、gpt-6-astra,详见 Google Cloud 官方文档):
# 1. 推荐使用 gcloud ADC 短期凭据(避免在本地硬盘存储长效 Service Account JSON 密钥)
gcloud auth application-default login
# 2. 配置环境变量指定你的 Google Cloud 项目 ID 与全局端点
export GOOGLE_CLOUD_PROJECT="my-gcp-ai-project-123"
export GOOGLE_CLOUD_LOCATION="global"
# 3. 启动 Codex CLI,在登录方式中选择:
# Sign in another way -> Use Google Cloud Vertex AI
codex
# 进入会话后输入 /model 即可直接切换 gpt-6.1-sol、gpt-6-luna 或 gpt-6-astra!
三、常见报错和解决方法(Troubleshooting)
报错 1:让 Agent 在 execute_code 中用 matplotlib 画了 Loss 曲线图或保存了 .pt 模型权重,但 MCP 返回结果里只有文字没有图片/文件
- 触发原因:根据 Colab MCP Endpoint 规范说明,
execute_code工具直接通过 MCP 响应体返回的主要是纯文本信息(标准输出stdout与标准错误stderr),不会直接在 JSON-RPC 载荷里塞入大体积二进制图片或模型权重文件。 - 解决方法:如果需要把训练生成的图表或
.safetensors权重传回本地,可以在execute_code中挂载 Google Drive / Cloud Storage(gsutil cp),通过独立的 HTTP 连接下载,或者直接使用支持文件回传的colab log --output result.ipynb(Colab CLI)。
报错 2:调用 create_runtime 申请 H100 或 TPU v6e 时返回权限拒绝或资源不可用
- 触发原因:Colab API 的硬件分配受双重约束——一是你当前的 Colab 订阅层级(免费用户通常只能申请 CPU 或基础 T4 GPU,H100 与 TPU v6e 需 Pro / Pro+ 或按量付费账户),二是 Google 机房当前的实时库存(Availability)与账号动态配额上限。
- 解决方法:在 Agent 的 System Prompt 或自动化脚本中,强制要求先调用
get_subscription和list_runtime_specs检查当前账号实际可分配的加速器列表,若H100不可用则自动降级申请L4或T4。
报错 3:只调用了 delete_session,以为云端 GPU 已经停止计费了
- 触发原因:概念混淆!在 Colab MCP 中,
delete_session只是关闭了该虚拟机里的一个 Python 内核进程,而底层的云端 GPU 虚拟机(Runtime)依然处于开机计费状态! - 解决方法:实验彻底结束后,必须显式调用
delete_runtime(或在 CLI 中执行colab stop),并通过list_runtimes确认返回列表为空,才能真正停止消耗 Colab Compute Units。
四、费用估算与使用建议
- 零门槛白嫖与低成本试错:对于学生和独立开发者,利用免费 Google 账号自带的 Colab Free T4 GPU 额度,配合 Claude Code / Gemini CLI(免费层每分钟 60 次请求、每天 1,000 次请求,见
[内链:Gemini API 12月涨价预警与免费层额度解析]),即可实现零硬件成本、零软件订阅费的本地 Agent + 云端 GPU 自动炼丹流水线。 - 何时选 MCP Endpoint,何时保留 Colab CLI?
- 如果你使用的是网页版/桌面版支持远程 MCP 挂载的客户端,或者希望 Agent 在同一个长会话里像操作 REPL 一样根据上一步的变量结果动态决定下一步代码,优先挂载
https://colaboratory.googleapis.com/mcp。 - 如果你的工作流是一次性把本地写好的整个
train.py扔上云端跑完并拿回包含可视化图表的.ipynb报告,继续在 Claude Code 里让它敲colab run --gpu T4 train.py反而更直接高效。
- 如果你使用的是网页版/桌面版支持远程 MCP 挂载的客户端,或者希望 Agent 在同一个长会话里像操作 REPL 一样根据上一步的变量结果动态决定下一步代码,优先挂载
五、总结
Google Colab API 与官方托管 MCP Endpoint(https://colaboratory.googleapis.com/mcp)的上线,标志着 Google Colab 正式从一个“给人手点的浏览器交互笔记本”蜕变为面向 AI 智能体的无头云端算力底座(Headless Compute Substrate)。只需花 10 分钟配好 OAuth 2.0 凭据并牢记在结束时调用 delete_runtime,你的每一台轻薄本都能瞬间拥有随叫随到的 H100 与 TPU v6e 集群。
常见问题
1. Google Colab API 和 MCP Endpoint 需要付费订阅 Colab Pro 才能用吗?
不需要! 根据 官方发布说明,全新的 Google Colab API 与 https://colaboratory.googleapis.com/mcp 端点向所有 Colab 用户(包括 Free 免费层用户)开放。不过,你能通过 API 申请到的具体 GPU/TPU 型号(例如能否申请到 H100 或 TPU v6e)以及运行时长,仍然取决于你账号当前的 Colab 订阅计划与剩余计算单元(Compute Units)。
2. 我已经在 Claude Code 里用熟了今年 6 月发布的 Colab CLI,有必要全部迁移到新的 Colab MCP Endpoint 吗?
不一定需要强行迁移。Colab MCP Endpoint 的优势在于提供标准化的 10 个 MCP 工具(无需本地安装 CLI 二进制包,且支持跨 execute_code 保持内存变量状态);但 Colab CLI(如 colab run --gpu T4 train.py 和 colab log --output)在上传本地脚本文件和导出带图表的 .ipynb 笔记本时依然更加直接。在具备终端执行能力的 Claude Code 或 Codex 中,两者完全可以按需混用。
3. 在 Google Cloud Vertex AI 中接入 OpenAI Codex CLI 目前支持调用哪些模型?
根据 Google Cloud 最新官方文档,配置好 GOOGLE_CLOUD_PROJECT 并通过 Use Google Cloud Vertex AI 登录后,目前可在 Codex CLI 与 Codex Desktop 中直接选择并调用三款合作模型:gpt-6.1-sol(主力编程与 Agent 模型)、gpt-6-luna(低延迟交互模型)以及 gpt-6-astra(高复杂度多步推理旗舰,关于最新 6.2 版本可参考 [内链:OpenAI GPT-6.2 Astra与Sol全面横评])。
参考来源
[Overview of Google Colab API and MCP Endpoint - Features, Usage, and Differences from Colab CLI - note (npaka)](https://note.com/npaka/n/ne69e426d97e9?hl=en)(2026-11-18)
[Connect OpenAI Codex to Google Cloud | Gemini Enterprise Agent Platform - Google Cloud Documentation](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/openai/codex)(2026-11-17 / 2026-11-18)
转载请注明出处:界智通 · https://www.jieagi.com/aizixun/653.html




暂无评论