Colab Drive MCP

Colab Drive MCP

一个 MCP 服务，可通过 Google Drive 安全地检查、编辑和同步 兼容 Google Colab 的 .ipynb 笔记本。

重要

这是一个笔记本文件同步服务，而非笔记本执行服务。 它通过 Google Drive 传输和编辑 .ipynb 文件。 它不会连接 Colab 运行时、执行单元格、点击 Run all、保持会话运行、 自动操作 Colab 浏览器界面，也不会绕过 Colab 限制。

当 AI Agent 需要在本地准备笔记本、将其与 Drive 同步、检查已完成的输出， 或将编辑后的笔记本交还给用户时，可以使用此 MCP。请在 Colab、Jupyter、 VS Code 或其他笔记本运行时中单独打开并执行已同步的笔记本。

功能

• 无需加载整个笔记本，即可检查和编辑笔记本单元格。
• 创建、搜索、复制、上传和下载笔记本。
• 向请求进度信息的 MCP 客户端报告实时上传和下载进度。
• 使用 Drive 元数据和内容 MD5 比较本地与 Drive 中的笔记本副本。
• 将本地文件访问限制在已配置的根目录内。
• 下载时规范化 Colab 专属的流输出元数据。
• 诊断 Google Drive 设置，且不会意外打开浏览器。
• 针对缺少凭据、授权过期、权限问题、文件缺失和速率限制返回可操作的错误信息。

非目标

• 启动、控制或监控 Google Colab 运行时。
• 检测 Colab 运行时是否已连接、正忙或正在执行文件。
• 在本地或远程执行笔记本单元格。
• 浏览器自动化、自动执行 Run all 或无人值守的 Colab 会话。
• 规避 Colab 配额、空闲超时、访问控制或使用政策。
• 部署或运行笔记本中包含的项目。

AI 使用约定

MCP 初始化响应包含适用于整个服务的指令，明确规定本项目仅用于文件同步。 相关工具的描述也会重申这一限制。

manifest.0 以类型化 Zero 语言约定的形式，为 Agent 和仓库工具提供相同的用途、功能和非目标说明。

工具

设置

• get_google_drive_status：诊断依赖项、凭据、令牌和作用域。
• authorize_google_drive：明确打开 Google OAuth 浏览器授权流程。

本地笔记本

• list_local_notebooks、get_local_notebook、create_local_notebook
• add_local_cell、update_local_cell、delete_local_cell
• search_local_cells、clear_local_outputs

Google Drive

• list_drive_notebooks、pull_drive_notebook、push_local_notebook
• get_notebook_sync_status、copy_drive_notebook、get_colab_url

pull_drive_notebook 和 push_local_notebook 用于同步笔记本文件。 当客户端提供进度令牌时，它们会发送 MCP 进度通知， 但是否显示这些通知以及如何显示由客户端决定。它们绝不会执行笔记本代码。 get_colab_url 会返回 URL，但不会打开浏览器。

get_notebook_sync_status 会将本地笔记本的上传表示形式与 Drive 的 MD5 校验和进行比较， 并返回 in_sync、differs、remote_only 或 unknown。它还会返回修改时间和版本等 Drive 元数据。 由于 Google Drive 不会公开 Colab 运行时的活动状态，因此无法判断 Colab 当前是否正在执行该笔记本。

安装

使用 uvx 直接从 PyPI 运行：

COLAB_MCP_ROOT="$HOME/notebooks" uvx --from 'colab-drive-mcp[drive]' colab-drive-mcp

或从源代码安装：

git clone https://github.com/YummyTastyCode/colab-drive-mcp.git
cd colab-drive-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[drive]'

运行服务：

COLAB_MCP_ROOT="$HOME/notebooks" .venv/bin/colab-drive-mcp

本地工具只能访问 COLAB_MCP_ROOT 下的 .ipynb 文件。

该服务已发布到官方 MCP Registry：

io.github.YummyTastyCode/colab-drive-mcp

Google Drive 设置

首先调用 get_google_drive_status。它不会打开浏览器或修改文件。其响应会说明接下来需要执行的步骤。

启用 Drive：

1. 创建 Google Cloud 项目。
2. 启用 Google Drive API。
3. 配置 OAuth 同意屏幕，并将你的账号添加为测试用户。
4. 创建应用类型为 桌面应用 的 OAuth Client ID。
5. 将 JSON 下载到 ~/.config/colab-mcp/credentials.json。
6. 调用 authorize_google_drive 并完成 Google 登录流程。

生成的令牌会存储在 ~/.config/colab-mcp/token.json。

使用以下变量覆盖这些位置：

• COLAB_MCP_GOOGLE_CREDENTIALS
• COLAB_MCP_GOOGLE_TOKEN

切勿提交 OAuth 凭据或令牌。

Drive 访问模式

默认模式为 file，使用 Google 权限范围较窄的 drive.file：

COLAB_MCP_DRIVE_ACCESS=file

此模式可以访问由此 OAuth 应用创建或明确打开的文件，但无法可靠地列出用户 Drive 中所有现有笔记本。

如需查找和更新现有 Drive 笔记本，请明确启用完全访问权限：

COLAB_MCP_DRIVE_ACCESS=full

更改访问模式可能需要删除 token.json 并再次调用 authorize_google_drive。

Codex 配置

codex mcp add colab-drive \
  --env COLAB_MCP_ROOT="$HOME/notebooks" \
  --env COLAB_MCP_DRIVE_ACCESS=file \
  -- /absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp

VS Code 配置

将此服务添加到 VS Code MCP 配置中：

{
  "servers": {
    "colab-drive": {
      "type": "stdio",
      "command": "/absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp",
      "env": {
        "COLAB_MCP_ROOT": "/absolute/path/to/notebooks",
        "COLAB_MCP_DRIVE_ACCESS": "file"
      }
    }
  }
}

Colab 兼容性

Google Colab 可能会在流输出中添加 metadata 属性。根据标准 nbformat v4 架构，该属性无效。在从 Drive 下载期间，此服务只会移除这个不兼容的属性。流文本和所有其他输出都会保留。

安全性

• OAuth 令牌保留在本地计算机上。
• 本地工具仅限访问 COLAB_MCP_ROOT。
• 授权需要显式调用 authorize_google_drive。
• 除非需要全面发现 Drive 内容，否则请使用 file 访问模式。
• 覆盖现有 Drive 文件前，请先检查操作。

本项目与 Google 无关联，也未获得 Google 背书。

开发

.venv/bin/pip install -e '.[drive,test]'
.venv/bin/pytest