{
  "markdown": "# Colab Drive MCP\n\n<!-- mcp-name: io.github.YummyTastyCode/colab-drive-mcp -->\n\n[![CI](https://github.com/YummyTastyCode/colab-drive-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YummyTastyCode/colab-drive-mcp/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/YummyTastyCode/colab-drive-mcp)](https://github.com/YummyTastyCode/colab-drive-mcp/releases)\n[![PyPI](https://img.shields.io/pypi/v/colab-drive-mcp)](https://pypi.org/project/colab-drive-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAn MCP server for safely inspecting, editing, and synchronizing\nGoogle Colab-compatible `.ipynb` notebooks through Google Drive.\n\n> [!IMPORTANT]\n> **This is a notebook file synchronization server, not a notebook execution\n> service.** It transfers and edits `.ipynb` files through Google Drive. It\n> does not connect to Colab runtimes, execute cells, click **Run all**, keep\n> sessions alive, automate the Colab browser UI, or bypass Colab limits.\n\nUse this MCP when an AI agent needs to prepare a notebook locally, synchronize\nit with Drive, inspect completed outputs, or return an edited notebook to the\nuser. Open and execute the synchronized notebook separately in Colab, Jupyter,\nVS Code, or another notebook runtime.\n\n## Features\n\n- Inspect and edit notebook cells without loading the entire notebook.\n- Create, search, copy, upload, and download notebooks.\n- Report live upload and download progress to MCP clients that request it.\n- Compare local and Drive notebook copies using Drive metadata and content MD5.\n- Keep local file access inside a configured root directory.\n- Normalize Colab-specific stream output metadata during downloads.\n- Diagnose Google Drive setup without unexpectedly opening a browser.\n- Return actionable errors for missing credentials, expired authorization,\n  permissions, missing files, and rate limits.\n\n## Non-goals\n\n- Starting, controlling, or monitoring a Google Colab runtime.\n- Detecting whether a Colab runtime is connected, busy, or executing a file.\n- Executing notebook cells locally or remotely.\n- Browser automation, automatic `Run all`, or unattended Colab sessions.\n- Circumventing Colab quotas, idle timeouts, access controls, or usage policies.\n- Deploying or running the project contained inside a notebook.\n\n## AI Contract\n\nThe MCP initialization response includes server-wide instructions that define\nthis project as file synchronization only. Tool descriptions repeat the same\nboundary where it matters.\n\n[`manifest.0`](manifest.0) provides the same purpose, capabilities, and\nnon-goals as a typed Zero language contract for agents and repository tooling.\n\n## Tools\n\n### Setup\n\n- `get_google_drive_status`: diagnose dependencies, credentials, token, and scope.\n- `authorize_google_drive`: explicitly open the Google OAuth browser flow.\n\n### Local notebooks\n\n- `list_local_notebooks`, `get_local_notebook`, `create_local_notebook`\n- `add_local_cell`, `update_local_cell`, `delete_local_cell`\n- `search_local_cells`, `clear_local_outputs`\n\n### Google Drive\n\n- `list_drive_notebooks`, `pull_drive_notebook`, `push_local_notebook`\n- `get_notebook_sync_status`, `copy_drive_notebook`, `get_colab_url`\n\n`pull_drive_notebook` and `push_local_notebook` synchronize notebook files.\nThey send MCP progress notifications when the client supplies a progress token,\nbut clients decide whether and how to display those notifications. They never\nexecute notebook code. `get_colab_url` returns a URL but does not open a browser.\n\n`get_notebook_sync_status` compares the local notebook's upload representation\nwith Drive's MD5 checksum and returns `in_sync`, `differs`, `remote_only`, or\n`unknown`. It also returns Drive metadata such as modification time and version.\nIt cannot determine whether Colab is currently executing the notebook because\nGoogle Drive does not expose Colab runtime activity.\n\n## Install\n\nRun directly from [PyPI](https://pypi.org/project/colab-drive-mcp/) with `uvx`:\n\n```bash\nCOLAB_MCP_ROOT=\"$HOME/notebooks\" uvx --from 'colab-drive-mcp[drive]' colab-drive-mcp\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/YummyTastyCode/colab-drive-mcp.git\ncd colab-drive-mcp\npython3 -m venv .venv\n.venv/bin/pip install -e '.[drive]'\n```\n\nRun the server:\n\n```bash\nCOLAB_MCP_ROOT=\"$HOME/notebooks\" .venv/bin/colab-drive-mcp\n```\n\nLocal tools can access only `.ipynb` files below `COLAB_MCP_ROOT`.\n\nThe server is published in the official MCP Registry as:\n\n```text\nio.github.YummyTastyCode/colab-drive-mcp\n```\n\n## Google Drive Setup\n\nFirst call `get_google_drive_status`. It does not open a browser or modify\nfiles. Its response explains the next required step.\n\nTo enable Drive:\n\n1. Create a Google Cloud project.\n2. Enable the Google Drive API.\n3. Configure the OAuth consent screen and add your account as a test user.\n4. Create an OAuth Client ID with application type **Desktop app**.\n5. Download the JSON to `~/.config/colab-mcp/credentials.json`.\n6. Call `authorize_google_drive` and complete the Google sign-in flow.\n\nThe resulting token is stored at `~/.config/colab-mcp/token.json`.\n\nOverride these locations with:\n\n- `COLAB_MCP_GOOGLE_CREDENTIALS`\n- `COLAB_MCP_GOOGLE_TOKEN`\n\nNever commit OAuth credentials or tokens.\n\n## Drive Access Modes\n\nThe default mode is `file`, using Google's narrower `drive.file` scope:\n\n```bash\nCOLAB_MCP_DRIVE_ACCESS=file\n```\n\nThis mode can access files created or explicitly opened by this OAuth app. It\ncannot reliably list all existing notebooks in a user's Drive.\n\nTo find and update existing Drive notebooks, explicitly enable full access:\n\n```bash\nCOLAB_MCP_DRIVE_ACCESS=full\n```\n\nChanging access modes may require deleting `token.json` and calling\n`authorize_google_drive` again.\n\n## Codex Configuration\n\n```bash\ncodex mcp add colab-drive \\\n  --env COLAB_MCP_ROOT=\"$HOME/notebooks\" \\\n  --env COLAB_MCP_DRIVE_ACCESS=file \\\n  -- /absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp\n```\n\n## VS Code Configuration\n\nAdd this server to the VS Code MCP configuration:\n\n```json\n{\n  \"servers\": {\n    \"colab-drive\": {\n      \"type\": \"stdio\",\n      \"command\": \"/absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp\",\n      \"env\": {\n        \"COLAB_MCP_ROOT\": \"/absolute/path/to/notebooks\",\n        \"COLAB_MCP_DRIVE_ACCESS\": \"file\"\n      }\n    }\n  }\n}\n```\n\n## Colab Compatibility\n\nGoogle Colab may add a `metadata` property to stream outputs. That property is\ninvalid under the standard nbformat v4 schema. During Drive downloads, this\nserver removes only that incompatible property. Stream text and all other\noutputs are preserved.\n\n## Security\n\n- OAuth tokens stay on the local machine.\n- Local tools are restricted to `COLAB_MCP_ROOT`.\n- Authorization requires an explicit `authorize_google_drive` call.\n- Use `file` access unless full Drive discovery is required.\n- Review actions before overwriting an existing Drive file.\n\nThis project is not affiliated with or endorsed by Google.\n\n## Development\n\n```bash\n.venv/bin/pip install -e '.[drive,test]'\n.venv/bin/pytest\n```\n",
  "bytes": 7065,
  "sha": "77f7ab1cd167be610ada63e348622e77a846bc1a1ebb17eb16b25a4609452fa1",
  "repo_slug": "yummytastycode/colab-drive-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yummytastycode_colab_drive_mcp_8d6e9ca3/readme"
}