Colab GPU Code Executor MCP Server

使用说明（Markdown 格式）

• 项目简介 这是一个基于 MCP（Model Context Protocol）的服务器端实现，能够通过 Google Colab 的 GPU 运行时执行 Python 代码。它对接 MCP 客户端，提供三种工具：colab_execute（执行内联代码）、colab_execute_file（执行本地 Python 文件）、colab_execute_notebook（执行代码并收集工件）。服务器负责分配 Colab 运行时、建立并控制 Jupyter kernel，会将执行结果以 JSON 形式返回给客户端，同时可把产出物打包并下载。

• 主要功能点

  • 提供三种工具：colab_execute、colab_execute_file、colab_execute_notebook。
  • 与 Google Colab API 交互：分配/释放 GPU 运行时、创建会话、通过 WebSocket 向 Colab 内核发送代码并获取输出。
  • 按代码单元包装输出，解析每个单元的 stdout/stderr，返回结构化结果。
  • 支持在 Colab 运行时收集产出物（图片、模型、CSV 等），打包并提供下载。
  • 通过 Keep-Alive、凭证缓存与异步传输等机制管理运行时生命周期。
  • 使用 MCP 的 FastMCP 框架暴露工具接口，支持通过标准 MCP 客户端进行调用。

• 安装步骤

  • 确保使用 Python 3.10 及以上版本。
  • 安装包并运行服务器：
    • pip install mcp-server-colab-exec
    • 或在开发环境直接运行服务器脚本（参考仓库提供的启动方式）。
  • 运行方式通常使用 MCP 客户端约定的传输通道（本实现使用 stdio 传输，可以通过 uvx 等工具启动）以接入 MCP 客户端。

• 服务器配置（MCP 客户端连接所需信息） 下面的配置信息仅用于 MCP 客户端在本仓库实现的服务端中注册和连接。MCP 客户端不需要该仓库的内部实现细节，只需要知道服务器名称、启动命令及参数即可建立连接。 { "serverName": "colab-exec", "command": "mcp-server-colab-exec", "args": [] }

• 基本使用方法

  1. 启动服务器 在兼容 MCP 的客户端配置完成后，使用提供的命令启动服务器（例如 uvx mcp-server-colab-exec 或等效命令）。服务器将通过 MCP 协议监听并等待客户端连接。
  2. 连接与调用工具 MCP 客户端注册后即可调用以下工具：
     • colab_execute：传入 Python 代码字符串，返回每个代码单元的输出、错误和退出码等信息。
     • colab_execute_file：传入本地文件路径，服务器将读取并在 Colab GPU 上执行，返回同样的结构化结果。
     • colab_execute_notebook：传入代码及输出目录，服务器执行并尝试收集并下载艺术品（工件）到本地输出目录。
  3. 处理结果 工具返回的结果为结构化的 JSON 字符串，包含 cells（每个单元的 stdout/状态）、错误信息、以及必要的 stderr 与 exit_code，部分命令还会返回 artifacts 的下载路径。
  4. 认证与运行时管理 服务器实现了 Google Colab 的 OAuth2 授权流程，以及运行时分配、keep-alive、内核会话等生命周期管理，确保在有网络环境的条件下持续运行。

• 重要注意事项

  • 该实现依赖外部 Google Colab 服务，请确保账户有权限创建 GPU 运行时且遵循 Google Colab 的使用限制。
  • Colab 运行时可能因配额、排队和网络原因导致执行延时或失败，请妥善处理错误输出与重试策略。
  • 出于安全考虑，执行来自 MCP 客户端的代码应在受控环境下进行，避免执行不受信任的代码。