mcp-server-colab-exec

mcp-server-colab-exec

可分配 Google Colab GPU 运行时（T4/L4）并在其中执行 Python 代码的 MCP 服务。让任何兼容 MCP 的 AI 助手——Claude Code、Claude Desktop、Gemini CLI、Cline 等——都能运行 GPU 加速代码（CUDA、PyTorch、TensorFlow），无需本地 GPU 硬件。

前置条件

• Python 3.10+
• 可访问 Google Colab 的 Google 账号
• 首次运行时，会打开浏览器窗口以获取 OAuth2 授权。令牌会缓存到 ~/.config/colab-exec/token.json，供后续运行使用。

安装

pip install mcp-server-colab-exec

或者使用 uvx 直接运行：

uvx mcp-server-colab-exec

配置

Claude Code

添加到项目的 .mcp.json 或 ~/.claude/.mcp.json：

{
  "mcpServers": {
    "colab-exec": {
      "command": "mcp-server-colab-exec"
    }
  }
}

或者通过 CLI：

claude mcp add colab-exec mcp-server-colab-exec

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "colab-exec": {
      "command": "mcp-server-colab-exec"
    }
  }
}

Gemini CLI

gemini mcp add colab-exec -- mcp-server-colab-exec

工具

colab_execute

在 Colab GPU 运行时上执行内联 Python 代码。

参数	类型	默认值	说明
code	string	—	要执行的 Python 代码（必填）
accelerator	string	"T4"	GPU 类型："T4"（免费）或 "L4"（高级）
timeout	int	300	最大执行时间（秒）

返回包含每个单元格的输出、错误和标准错误流的 JSON。

colab_execute_file

在 Colab GPU 运行时上执行本地 .py 文件。

参数	类型	默认值	说明
file_path	string	—	本地 .py 文件的路径（必填）
accelerator	string	"T4"	GPU 类型："T4"（免费）或 "L4"（高级）
timeout	int	300	最大执行时间（秒）

安全策略：file_path 必须是当前工作区（cwd）内的 .py 文件。

colab_execute_notebook

执行代码并收集所有生成的产物（图像、CSV、模型等）。

参数	类型	默认值	说明
code	string	—	要执行的 Python 代码（必填）
output_dir	string	—	用于存放下载产物的本地目录（必填）
accelerator	string	"T4"	GPU 类型："T4"（免费）或 "L4"（高级）
timeout	int	300	最大执行时间（秒）

产物会以 zip 文件形式下载并解压到 output_dir。 解压前会验证 zip 文件成员，以防止路径遍历和写入特殊文件。

示例

检查 GPU 是否可用：

colab_execute(code="import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))")

运行 nvidia-smi：

colab_execute(code="import subprocess; print(subprocess.run(['nvidia-smi'], capture_output=True, text=True).stdout)")

训练模型并下载权重：

colab_execute_notebook(
    code="import torch; model = torch.nn.Linear(10, 1); torch.save(model.state_dict(), '/tmp/model.pt')",
    output_dir="./outputs"
)

身份验证

首次使用时，服务会打开浏览器窗口以获取 Google OAuth2 授权。访问令牌和刷新令牌会缓存到 ~/.config/colab-exec/token.json。后续运行会使用缓存的令牌并自动刷新。

OAuth2 客户端凭据与官方 Google Colab VS Code 扩展（[email protected]）使用的相同。这些凭据有意公开。

故障排除

“GPU 配额已超限” — Colab 有使用限制。请稍后重试，或改用其他 Google 账号。

“创建内核会话超时” — 运行时启动耗时过长。请重试——Colab 在使用高峰期有时会出现延迟。

“身份验证失败” — 删除 ~/.config/colab-exec/token.json 并重新进行身份验证。

OAuth 浏览器窗口未打开 — 请确保你正在有浏览器的环境中运行。对于无头服务，先在有浏览器的机器上进行身份验证，然后复制令牌文件。

许可证

MIT