Colab MCP

What SebastianGilPinzon/colab-mcp MCP server does

SebastianGilPinzon/colab-mcp MCP server exposes Google Colab notebook operations to MCP-compatible AI clients. The notebook workflow starts by opening a browser connection to a Colab notebook. Once connected, an agent can inspect the notebook, create or modify cells, execute code, and manage cell order.

The server also includes a runtime control operation. With Google OAuth enabled, an agent can request the T4, L4, A100, or NONE accelerator. Notebook editing and execution use the browser connection, while runtime selection requires OAuth credentials.

How it works

The server runs locally and communicates with an MCP client over standard input and output. Its proxy component connects the local process to browser-based Colab notebook tools. The fork pre-registers its tools so clients can see the notebook operations at startup rather than waiting for a tool-list change notification.

A typical session calls open_colab_browser_connection, then uses the returned notebook context with operations such as add_code_cell, run_code_cell, and get_cells. Cell operations identify their targets with cellId; the older cellIndex fallback is not supported. The server records running instances in a small registry, prunes stale entries when starting, and provides commands for listing or terminating stale processes.

Setup and configuration

Install uv using the project’s documented installer instructions, then run the project with uv or the repository’s uvx Git reference. An MCP client configuration points command to uv and passes run, --directory, the local repository path, and colab-mcp as arguments. The repository example uses a 30-second client timeout.

Notebook control can be configured without OAuth. To enable change_runtime, create a Google Cloud project, configure an OAuth consent screen, add a test user, create a Desktop OAuth client, and pass the downloaded client-secrets JSON with --client-oauth-config. On first launch, the browser-based consent flow authorizes access. The resulting token is cached at ~/.colab-mcp-auth-token.json and refreshed automatically.

On Windows, the server uses port 8085 for compatibility. Its registry is stored under %LOCALAPPDATA%\\colab-mcp\\registry.json on Windows and ~/.colab-mcp/registry.json on macOS or Linux.

Tools and capabilities

SebastianGilPinzon/colab-mcp MCP server provides these operations:

• open_colab_browser_connection: connect to a Colab notebook in the browser.
• get_cells: read cell IDs, contents, notebook state, and outputs.
• add_code_cell: insert executable code.
• add_text_cell: insert a Markdown cell.
• run_code_cell: execute a cell by cellId.
• update_cell: edit an existing cell by cellId.
• delete_cell: remove a cell by cellId.
• move_cell: reposition a cell by cellId.
• change_runtime: select T4, L4, A100, or NONE when OAuth is configured.

Limitations and notes

Browser-dependent notebook operations require an active Colab browser connection. Runtime selection is unavailable unless the server starts with a valid OAuth client configuration.

Define the MCP server in only one client configuration file. Duplicate global and project definitions can start competing instances and cause one to fail. If Colab reports that it is disconnected from the local server, --list-running can show active instances and --kill-stale can terminate them before a new session starts. The latter should be run from a regular shell, not inside Claude Code.

The project is licensed under Apache-2.0 and requires Python 3.11 or newer.