金大哥 - mcp-server-colab-exec MCP 详情

article

README

🚀 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 代码。 | 参数 | 类型 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | code | 字符串 | — | 要执行的 Python 代码（必需） | | accelerator | 字符串 | "T4" | GPU 类型："T4"（免费）或 "L4"（高级） | | timeout | 整数 | 300 | 最大执行时间（秒） | 该工具返回包含每个单元格输出、错误信息和标准错误的 JSON 数据。

`colab_execute_file`

该工具用于在 Colab GPU 运行时执行本地 .py 文件。 | 参数 | 类型 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | file_path | 字符串 | — | 本地 .py 文件的路径（必需） | | accelerator | 字符串 | "T4" | GPU 类型："T4"（免费）或 "L4"（高级） | | timeout | 整数 | 300 | 最大执行时间（秒） | 安全策略：file_path 必须是当前工作空间（cwd）内的 .py 文件。

`colab_execute_notebook`

该工具用于执行代码并收集所有生成的工件（如图像、CSV、模型等）。 | 参数 | 类型 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | code | 字符串 | — | 要执行的 Python 代码（必需） | | output_dir | 字符串 | — | 用于下载工件的本地目录（必需） | | accelerator | 字符串 | "T4" | GPU 类型："T4"（免费）或 "L4"（高级） | | timeout | 整数 | 300 | 最大执行时间（秒） | 工件将以 zip 文件形式下载并提取到 output_dir。在提取之前，会对 zip 文件的成员进行验证，以防止路径遍历和特殊文件写入。

🔑 认证说明

首次使用时，服务器会打开一个浏览器窗口进行 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 许可证。

mcp-server-colab-exec