SebastianGilPinzon/colab-mcp

An MCP server for controlling Google Colab from any AI coding agent. This fork fixes the bugs in the official repo that block real day-to-day use and restores features Google removed upstream.
Why This Fork?
Three concrete dolores that the official googlecolab/colab-mcp doesn't solve — and that this fork does:
1. **Invisible tools** (#54, #67, #69) — only open_colab_browser_connection appears in most MCP clients (Claude Code, Codex, Kiro IDE). The notebook tools rely on notifications/tools/list_changed, which these clients ignore. Without get_cells in particular, the bridge is effectively write-only: an agent can add cells but can't read state back.
2. **"Disconnected from the local Colab MCP server"** (#84) — orphaned servers from prior Claude Code sessions hold ports that your browser tab still points at. Reconnecting from the tab silently fails.
3. **No programmatic GPU control** — Google removed the --enable-runtime feature entirely. You can't assign T4 / L4 / A100 without clicking in the browser.
This fork fixes all three. All 9 tools (1 connection + 7 notebook + 1 GPU control) appear immediately, stale servers are auto-detected and clean-uppable, and GPUs are assignable from a single tool call.
> _Demo coming soon: docs/demo.gif (TODO — short asciinema of change_runtime → add_code_cell → run_code_cell)._
What's Different
| Feature | Official | This Fork |
|---------|----------|-----------|
| Notebook tools visible at startup | No (needs browser + list_changed) | Yes (pre-registered, works with any client) |
| change_runtime tool (GPU control) | Removed | Working via OAuth |
| OAuth token caching | N/A | Yes (authorize once, cached forever) |
| Windows compatibility | Port 53919 blocked | Fixed (port 8085) |
| ColabClient initialization | N/A | Fixed (Prod() env argument) |
| Stale-server detection / cleanup | None — silent "Disconnected" | --list-running + --kill-stale, registry pruning on startup |
Available Tools
| Tool | Requires Browser | Requires OAuth | Description |
|------|:---:|:---:|-------------|
| change_runtime | | Yes | Assign GPU: T4, L4, A100, or NONE |
| open_colab_browser_connection | Yes | | Connect to a Colab notebook in your browser |
| add_code_cell | Yes | | Add a code cell to the notebook |
| add_text_cell | Yes | | Add a markdown cell |
| get_cells | Yes | | Read current notebook state (cells, IDs, contents, outputs) |
| run_code_cell | Yes | | Execute a code cell by cellId |
| update_cell | Yes | | Edit an existing cell by cellId |
| delete_cell | Yes | | Delete a cell by cellId |
| move_cell | Yes | | Move a cell to a new position by cellId |
> **Note:** execute_cell was renamed to run_code_cell in 2026-06-16 to match the browser-side handler name. Pass a cellId (from add_code_cell or get_cells) — the old cellIndex fallback was removed.
Quick Start (Without OAuth)
If you just want the notebook tools (no change_runtime):
1. Install uv
**Important:** Do NOT use pip install uv — that version lacks required features.
2. Clone this repo
3. Configure your MCP client
Add to your .mcp.json (Claude Code, Cursor, etc.):
4. Use it
1. Restart your editor / reload window
2. All 8 tools should appear immediately (open_colab_browser_connection + 7 notebook tools)
3. Call open_colab_browser_connection — a Colab notebook opens in your browser
4. Use add_code_cell, run_code_cell, get_cells, etc. to control the notebook
---
Full Setup (With OAuth + GPU Control)
This enables the change_runtime tool, which lets your agent assign GPUs without you touching the browser.
1. Create OAuth Credentials
You need a Google Cloud project with OAuth configured. This is a one-time setup (~5 minutes):
1. **Create a GCP project** (or use an existing one):
2. **Configure OAuth consent screen:**
- Go to OAuth consent screen
- Select "External" > Create
- App name: Colab MCP, add your email as support + developer contact
- Save through all steps
3. **Add yourself as test user:**
- On the consent screen page > "Test users" > Add your Google email