MCP Server Colab Exec

🚀 mcp-server-colab-exec

mcp-server-colab-exec 是一个 MCP 服务器，它能够分配 Google Colab 的 GPU 运行时（T4/L4），并在其上执行 Python 代码。借助该服务器，任何与 MCP 兼容的 AI 助手，如 Claude Code、Claude Desktop、Gemini CLI、Cline 等，都可以在无需本地 GPU 硬件的情况下运行 GPU 加速代码（CUDA、PyTorch、TensorFlow）。

🚀 快速开始

在使用 mcp-server-colab-exec 之前，你需要满足以下前提条件：

• Python 3.10 及以上版本
• 拥有一个可以访问 Google Colab 的 Google 账户
• 首次运行时，会打开一个浏览器窗口进行 OAuth2 授权。授权令牌会被缓存到 ~/.config/colab-exec/token.json，后续运行将使用该缓存令牌。

📦 安装指南

你可以使用以下命令安装 mcp-server-colab-exec：

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

💻 使用示例

基础用法

检查 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"
)

📚 详细文档

colab_execute

该工具用于在 Colab GPU 运行时执行内联 Python 代码。

colab_execute_file

该工具用于在 Colab GPU 运行时执行本地 .py 文件。

colab_execute_notebook

该工具用于执行代码并收集所有生成的工件（如图像、CSV、模型等）。

🔑 认证说明

首次使用时，服务器会打开一个浏览器窗口进行 Google OAuth2 授权。访问令牌和刷新令牌会被缓存到 ~/.config/colab-exec/token.json。后续运行将使用缓存的令牌，并自动刷新。 OAuth2 客户端凭证与官方 Google Colab VS Code 扩展（google.colab@0.3.0）使用的凭证相同，这些凭证是公开的。

❓ 故障排除

• “GPU 配额已超出” — Colab 有使用限制，请等待一段时间后重试，或者使用不同的 Google 账户。
• “创建内核会话超时” — 运行时启动时间过长，请重试，因为 Colab 在高峰时段有时会出现延迟。
• “认证失败” — 删除 ~/.config/colab-exec/token.json 文件，然后重新进行认证。
• OAuth 浏览器窗口未打开 — 请确保你在支持浏览器的环境中运行。对于无头服务器，可先在有浏览器的机器上进行认证，然后复制令牌文件。

📄 许可证

本项目采用 MIT 许可证。