Skip to main content
Glama
colab-cloud-mcp
by Goudu666

colab-cloud-mcp

让 Claude 云端对话(网页 / 手机 App / Desktop Custom Connectors)、Google Antigravity 以及 Claude Code 通过公网 HTTPS (443) Streamable HTTP 协议直接连接 Google Colab GPU 运行时的远程 MCP Server。

为什么需要这个项目?

本地 stdio 模式的 Colab MCP 依赖本机 CLI 进程与本机浏览器标签页桥接——一旦合上笔记本电脑、休眠或本地网络闪断,连接就会立即断开,且无法在网页版或手机端云对话中使用。

colab-cloud-mcp 将 MCP 服务端直接运行在 Google Colab 虚拟机内部,并通过 HTTPS 隧道(Cloudflare Tunnel 或 ngrok)暴露符合最新规范的 Streamable HTTP 端点:

  • 真正脱离本机:云端对话客户端直接访问 Colab 端服务,本机合盖、断网或切换到手机端对话均不断连。

  • 持久化 Python 命名空间 + 自动捕获图表:execute_python 跨轮次保留所有变量、PyTorch 模型与显存张量;Matplotlib 绘图自动转为 PNG 图像块回传给对话界面。

  • 异步后台长任务管理:针对云端单次工具调用超时限制(Claude 240s / Antigravity 默认 180s),内置 start_background_job / get_job_status / cancel_job,支持数小时模型训练或大权重下载至 Google Drive,随时在对话中拉取最新日志。

  • 会话导出为 .ipynb:随时调用 export_session_notebook 将执行过的所有代码与输出图像保存为标准 Jupyter Notebook。

  • 三重鉴权兼容所有客户端:

    1. 零请求头加密路径模式(<TUNNEL_URL>/s/<MCP_TOKEN>/mcp):适配 Claude Custom Connectors 的 No sign in 模式,粘贴单条 URL 即可安全鉴权。

    2. 标准 Bearer Header 模式(Authorization: Bearer <MCP_TOKEN>):适配 Google Antigravity mcp_config.json、Claude Code HTTP MCP 与 Claude Request Headers。

    3. 内置 OAuth 2.1 (PKCE + DCR + CIMD):完整实现 /.well-known/oauth-protected-resource、/.well-known/oauth-authorization-server、动态客户端注册与 PKCE 授权码流程。

Related MCP server: Smart Colab MCP Bridge

快速开始(在 Google Colab 中运行)

打开本仓库的 notebooks/colab_cloud_mcp.ipynb 按顺序执行即可启动服务并打印所有客户端接入配置。

合盖前在最后一个单元格运行保活监控:

mcp_server.keep_alive(status_interval_seconds=60)

Colab 实例生命周期提示:MCP 连接本身已完全脱离本机,但 Google Colab 对免费版/Pro 版在关闭全部浏览器标签页后仍有后台空闲回收时间窗口;如需合盖后持续运行数小时,建议配合 keep_alive() 或 Colab Pro+ 后台执行,并将日志与权重保存至 /content/drive/MyDrive。

固定域名配置(重启 Colab 免改客户端 URL)

在 Colab 左侧 Secrets 中配置以下密钥并以 provider="auto" 启动:

方案

Colab Secrets 变量名

说明

固定鉴权密钥

MCP_TOKEN

自定义高强度字符串,重启免改 Token

Cloudflare Named Tunnel

CLOUDFLARE_TUNNEL_TOKEN、CLOUDFLARE_HOSTNAME

在 Cloudflare Zero Trust Tunnel 将子域名指向本地端口 8765

ngrok 免费静态域名

NGROK_AUTHTOKEN、NGROK_DOMAIN

使用 ngrok 账号免费静态域名(需安装 pyngrok)

客户端接入指南

1. Claude 云端(Custom Connectors)

  • 进入 Customize -> Connectors -> + Add -> Add custom connector

  • 最简方式(免配 Header):URL 填入启动器打印的 <TUNNEL_URL>/s/<MCP_TOKEN>/mcp,Authentication 选择 No sign in

  • Header / OAuth 方式:URL 填入 <TUNNEL_URL>/mcp,在 Request headers 添加 Authorization: Bearer <MCP_TOKEN> 或选择 OAuth 授权

2. Google Antigravity(App / IDE / CLI)

编辑 ~/.gemini/config/mcp_config.json 或工作区 .agents/mcp_config.json:

{
  "mcpServers": {
    "colab-remote": {
      "serverUrl": "<TUNNEL_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      },
      "timeoutSeconds": 600
    }
  }
}

3. Claude Code CLI

claude mcp add --transport http colab-remote <TUNNEL_URL>/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

内置 MCP 工具一览

工具名称

功能说明

get_runtime_status

查看 GPU 型号与显存 (nvidia-smi)、CPU/内存/磁盘、PyTorch CUDA 状态、Google Drive 挂载情况与后台任务数

execute_python

在持久化命名空间执行 Python 代码,自动捕获 stdout/stderr、返回值及 Matplotlib PNG 图像

reset_python_namespace

清空持久化变量并触发 gc.collect() 与 torch.cuda.empty_cache() 释放显存

run_shell

执行 Bash 命令(支持工作目录与超时进程组清理)

install_packages

通过 pip 安装或升级 Python 依赖包

start_background_job

异步启动长时间后台训练或大权重下载任务,日志实时落盘

get_job_status / list_jobs / cancel_job

查询后台任务状态与末尾日志、列出或终止后台任务

list_files / read_file / write_file

浏览、按行读取或写入 Colab 工作区与 Google Drive 文件

export_session_notebook

将当前会话执行过的所有代码与图表导出为 .ipynb 文件

本地测试

python3 tests/test_server.py

License

MIT

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