Skip to main content
Glama

Google Colab MCP Server (colabmcp)

MCP Version Python Version License

A production-grade Model Context Protocol (MCP) server bridging autonomous AI coding assistants (Claude Desktop, Cursor, Antigravity, Cline, Roo-Code, Windsurf) with consumer Google Colab (colab.research.google.com).

Run Python code, train deep learning models, execute complete Jupyter notebooks, and inspect multimodal visualizations (Matplotlib/Seaborn plots) directly in Google's cloud GPU and TPU environments without manual browser intervention.


🌟 Key Features

  • Consumer Colab Automation: Connects directly to Google Colab's Tunnel Frontend (TFE) without requiring enterprise GCP / Vertex AI configurations.

  • Hardware Acceleration on Demand: Provision and switch between standard CPU, NVIDIA GPUs (Tesla T4, L4, A100, H100), and Google Cloud TPUs (v5e, v6e). High-RAM shapes (~51 GB) supported for Pro/Pro+ accounts.

  • Pre-Assignment Session Re-attachment: Enumerates active sessions (/tun/m/assignments) to re-attach to existing VMs matching requested accelerators, preventing HTTP 412 quota rejection on Free Tier accounts.

  • Multi-Account Support: Seamless switching and parameterization via auth_user_index (default: 0) mapped to ?authuser=N query parameters and X-Goog-AuthUser: N headers.

  • Robust Google Authentication:

    • OAuth 2.0 Remote Flow: Copy-paste authorization code for headless and remote terminal setups.

    • Local Loopback Flow: Seamless local browser authorization.

    • Ambient ADC: Automatic reuse of existing gcloud auth application-default login credentials.

    • Chrome CDP Fallback: Real Chrome automation via Chrome DevTools Protocol with subprocess DEVNULL stdout isolation (preventing JSON-RPC framing corruption) and OSID cookie verification.

  • OS-Native Keystore Storage: Credentials securely encrypted via Windows DPAPI, macOS Keychain, or Linux Secret Service (with AES-256-GCM file fallback).

  • Persistent Keep-Alive Daemon & 30-Min Watchdog: Background heartbeat pinging /tun/m/{endpoint}/keep-alive/ every 35s with an in-memory activity watchdog that automatically invokes unassign_runtime after 30 minutes of inactivity to protect paid compute units.

  • Full Jupyter Messaging Protocol v5.3: Direct WebSocket communication with intermediate kernel discovery/creation (GET/POST /api/kernels), RFC 6455 compliant handshake (subprotocols=None), dynamic header fallback (additional_headers/extra_headers for websockets v13+/v16.0), and SIGINT / kernel restart distinction (state_reset, kernel_restarted).

  • Chronological Multimodal MIME Translation: Matplotlib and Seaborn plots are interleaved chronologically with stdout/stderr as MCP ImageContent and TextContent blocks, protected by head-tail truncation safety bounds (max_text_lines, max_output_bytes, max_images).

  • ECMA-48 Compliant ANSI Sanitizer: Complete stripping of CSI, OSC (with multiline (?s:\].*?(?:\x1b\\|\x07)) support), VT100, and Fe control sequences from execution traces.

  • Complete Notebook (.ipynb) Engine: Load, validate, execute (sequentially or by 0-based absolute cell index in nb.cells), optional kernel reset before run, structured failure diagnostics (error_name, error_value, traceback), and save notebooks back to disk using nbformat v4.

  • Dual Transports: Standard I/O (stdio) JSON-RPC with strict stdout isolation, plus Server-Sent Events (sse) for remote or multi-agent hub deployments.

  • Compute Unit Runaway Protection & Free Tier Quotas: Explicit error handling distinguishing HighRamNotAvailableError (HTTP 400), TOO_MANY_ASSIGNMENTS, CCU_EXHAUSTED, and FREE_TIER_QUOTA_EXCEEDED (HTTP 412).


Related MCP server: colab-autopilot

🏗️ Architecture

+-----------------------------------------------------------------------------------------+
|                                    AI AGENT HOST                                        |
|             (Claude Desktop / Cursor / Antigravity / Windsurf / VS Code Cline)          |
+-----------------------------------------------------------------------------------------+
                                             |
                                             | MCP Protocol (JSON-RPC 2.0)
                                             v
+=========================================================================================+
|                              COLAB MCP SERVER ENGINE                                    |
|                                                                                         |
|  +-----------------------------+               +-------------------------------------+  |
|  |     stdio Transport         |               |       SSE Transport (HTTP)          |  |
|  |  - JSON-RPC over stdin/out  |               |  - GET /sse (Event Stream)          |  |
|  |  - Stderr logger isolation  |               |  - POST /messages (RPC Dispatch)    |  |
|  +-----------------------------+               +-------------------------------------+  |
|                 |                                                 |                     |
|                 +------------------------+------------------------+                     |
|                                          |                                              |
|                                          v                                              |
|  +-----------------------------------------------------------------------------------+  |
|  |                             FastMCP Tool Dispatcher                               |  |
|  |   - Pydantic v2 schema validation & Credential Redaction Filter                   |  |
|  +-----------------------------------------------------------------------------------+  |
|            |                                |                               |           |
|            v                                v                               v           |
|  +--------------------+          +--------------------+          +--------------------+ |
|  |    Auth Module     |          |   Runtime Engine   |          |   Kernel Engine    | |
|  | - OAuth 2.0 Client |          | - TFE REST Client  |          | - WebSocket Client | |
|  | - CDP Automation   |          | - Session Manager  |          | - Jupyter v5.3 Wire| |
|  | - OS Keyring Store |          | - Keep-Alive Task  |          | - MIME Converter   | |
|  +--------------------+          +--------------------+          +--------------------+ |
+=========================================================================================+
            |                                           |                     |
            | Bearer Token                              | HTTPS TFE REST      | WSS Proxy
            v                                           v                     v
+------------------------+                 +------------------------+   +-----------------+
|  Google Accounts /     |                 |  Colab Tunnel Frontend |   | Remote Colab VM |
|  OAuth 2.0 Endpoint    |                 |  (TFE /tun/m/...)      |   | Jupyter Kernel  |
|  (accounts.google.com) |                 |  (Allocation & Status) |   | (IPython Core)  |
+------------------------+                 +------------------------+   +-----------------+

🚀 Installation & Quick Start

1. Installation

Install via pip or run directly with uvx / pipx:

# Using pip
pip install colab-mcp

# Or install with Playwright browser dependencies (for CDP fallback)
pip install "colab-mcp[browser]"
playwright install chromium

2. Configuration with AI Agent Hosts

Claude Desktop Configuration

Add colab-mcp to your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "colab": {
      "command": "uvx",
      "args": ["colab-mcp", "run"]
    }
  }
}

Or using an explicit Python virtual environment:

{
  "mcpServers": {
    "colab": {
      "command": "python",
      "args": ["-m", "colab_mcp", "run"]
    }
  }
}

Cursor / Antigravity / Windsurf Configuration

In your client's MCP configuration settings (Settings ➔ Features ➔ MCP Servers), add:

  • Server Name: colab

  • Transport: stdio

  • Command: colab-mcp

  • Arguments: ["run"]


🔑 Authentication Guide

Before provisioning runtimes, authenticate your Google account using one of the following methods:

  1. Ask your agent to call colab_login(method="oauth_remote") or run in terminal:

    colab-mcp login --method oauth_remote
  2. The server outputs a Google authorization URL. Open the link in any browser, log in with your Google account, and grant access.

  3. Copy the resulting authorization code from https://sdk.cloud.google.com/applicationdefaultauthcode.html.

  4. Provide the code back to the agent or paste into the terminal prompt.

  5. Tokens are securely encrypted into your OS Keyring.

Method B: Local Loopback OAuth (Desktop Environments)

colab-mcp login --method oauth_loopback

Spawns your local system browser, receives the OAuth callback on http://127.0.0.1:<port>, and securely saves the token.

Method C: Chrome CDP Browser Fallback

For environments where OAuth apps are restricted by Google Workspace policies:

colab-mcp login --method cdp_browser

Launches an authentic Google Chrome window with remote debugging enabled (--remote-debugging-port=9222), allowing you to complete standard login and 2FA. Session cookies are automatically extracted and encrypted.


🛠️ Complete MCP Tool Reference

colabmcp provides 13 granular tools across three functional categories:

1. Authentication Tools

Tool Name

Parameters

Description

colab_login

method (oauth_remote | oauth_loopback | oauth_adc | cdp_browser | cookie_import), auth_user_index, auth_code, cookies, timeout_seconds

Authenticate with Google Colab and store encrypted credentials in OS keystore. Supports multi-account user indexing.

colab_get_auth_status

auth_user_index (integer, default 0), force_refresh (boolean)

Query active account identity, token validity, and Colab Compute Unit (CCU) balance.

colab_logout

auth_user_index (integer, default 0), terminate_active_runtimes (boolean)

Wipe stored credentials from OS keystore and optionally terminate cloud runtimes.

2. Runtime Management Tools

Tool Name

Parameters

Description

colab_list_runtime_types

auth_user_index (integer, default 0)

Query available accelerators (CPU, T4, L4, A100, TPU), RAM shapes, and hourly compute unit costs.

colab_list_sessions

auth_user_index (integer, default 0), probe_kernels (boolean, default true)

List all active remote and locally tracked Colab VM sessions (including browser or prior-run sessions) and live kernel states.

colab_connect_runtime

accelerator (NONE | T4 | L4 | A100 | H100 | V5E1 | V6E1), high_ram (boolean), reuse_existing (boolean), auth_user_index (integer, default 0), timeout_seconds

Provision or re-attach to a Colab container VM and initialize kernel WebSocket. Re-attaches to active matching sessions (reuse_existing=True) to prevent HTTP 412 quota rejection on Free Tier. High-RAM strictly requires Pro/Pro+.

colab_get_runtime_status

runtime_id (optional string)

Check VM health, live CPU/RAM/VRAM/disk utilization, kernel state, and idle timer.

colab_disconnect_runtime

runtime_id (optional string), disconnect_all (boolean, default false), auth_user_index (integer, default 0)

Release one or all local/remote Colab VMs via /unassign to immediately halt compute unit consumption.

3. Execution & Output Monitoring Tools

Tool Name

Parameters

Description

colab_execute_code

code (string), runtime_id, timeout_seconds, wait_for_completion, store_history, max_text_lines, max_output_bytes, max_images

Execute Python code snippet; returns chronological multimodal content ([TextContent, ImageContent, TextContent]) with head-tail truncation safety bounds.

colab_execute_notebook

notebook_path | notebook_content, reset_kernel_before_run (boolean, default true), cell_indices (0-based absolute in nb.cells), stop_on_error, timeout_per_cell_seconds, output_save_path

Execute complete .ipynb notebook sequentially or selectively; captures structured failure diagnostics (error_name, error_value, traceback) and writes outputs back to disk.

colab_get_execution_status

execution_id (string)

Poll execution progress, elapsed time, and partial stdout for asynchronous jobs.

colab_get_cell_output

execution_id (string), include_images, max_text_lines, max_output_bytes, max_images

Retrieve full buffered outputs in strict chronological kernel emission order for an execution ID.

colab_interrupt_execution

runtime_id (optional string)

Dispatch SIGINT interrupt; escalates to kernel restart if unhalted within 5.0s. Returns state_reset and kernel_restarted status flags.


⚡ Hardware Accelerators & Pricing

Colab provides various hardware tiers depending on account subscription:

Accelerator ID

Hardware Device

VRAM / HBM

High-RAM (~51 GB)

Free Tier

Approx. Cost

NONE

2 vCPU Intel Xeon

None

❌ Pro/Pro+ only (Not on Free Tier)

✅ Yes

0.00 CCU/hr

T4

NVIDIA Tesla T4

16 GB GDDR6

❌ Pro/Pro+ only (Not on Free Tier)

✅ Yes (Dynamic)

~1.96 CCU/hr

L4

NVIDIA L4 Tensor Core

24 GB GDDR6

Supported

❌ Pro/Pro+

~3.84 CCU/hr

A100

NVIDIA A100-SXM4

40 GB / 80 GB

Supported

❌ Pro/Pro+

~5.42 - 11.2 CCU/hr

H100

NVIDIA H100-SXM5

80 GB HBM3

Supported

❌ Pro+

~13.50 CCU/hr

V5E1

Cloud TPU v5e

16 GB HBM

Standard Shape

❌ Pro/Pro+

~1.96 CCU/hr

V6E1

Cloud TPU v6e

32 GB HBM

Standard Shape

❌ Pro+

~4.50 CCU/hr

Important Note on Free Tier Restrictions:

  1. High-RAM shapes (shape=hm, ~51.0 GB RAM) are strictly restricted to paid Colab Pro/Pro+ tiers. Free Tier requests for High-RAM return HTTP 400 Bad Request (HighRamNotAvailableError).

  2. Free Tier allows only 1 concurrent GPU container VM. colab_connect_runtime defaults to reuse_existing=True to query active sessions via GET /tun/m/assignments and re-attach rather than attempting duplicate allocations that trigger HTTP 412 (TooManyAssignmentsError or FreeTierQuotaExceededError).


🛡️ Security Architecture

  1. Credential Isolation & Redaction: OAuth access tokens (ya29...), refresh tokens (1//0...), and full Google session cookies (SAPISID, OSID, etc.) are stripped by a global egress redaction filter before payloads reach LLM context.

  2. Encrypted Storage: Secrets are managed via OS-native vaults (Windows DPAPI, macOS Keychain, Linux Secret Service). Headless servers utilize AES-256-GCM encryption with 0600 file permissions.

  3. Execution Sandbox: All code execution occurs inside Google's cloud containers. No arbitrary code is evaluated locally on the host machine.

  4. Compute Unit Protection & 30-Min Inactivity Watchdog: Mandatory execution timeouts and an active keep-alive watchdog automatically deallocate runtimes (unassign_runtime) after 30 minutes of inactivity to prevent runaway credit depletion.

  5. ECMA-48 ANSI Traceback Sanitization: All terminal escape sequences (CSI, OSC via r'|(?s:\].*?(?:\x1b\\|\x07))', VT100, and Fe control characters) are stripped to prevent context bloat and terminal emulation exploits.

  6. CDP Subprocess Stdout Isolation: Chrome automation launches with stdout=subprocess.DEVNULL and stderr=subprocess.DEVNULL to prevent browser diagnostics from corrupting stdio JSON-RPC transport framing.


🗓️ Phased Implementation Roadmap

  • Milestone 1 (M1): Authentication & Credential Storage (OAuth 2.0 remote/loopback/ADC, CDP browser fallback, OS keyring).

  • Milestone 2 (M2): Runtime Lifecycle & Provisioning Engine (TFE client, hardware selector, keep-alive heartbeat).

  • Milestone 3 (M3): Kernel WebSocket Bridge & Output Pipeline (Jupyter protocol v5.3, multimodal MIME parser, SIGINT interrupt).

  • Milestone 4 (M4): Notebook Orchestration Engine (nbformat v4 loader, sequential/selective runner, serialization).

  • Milestone 5 (M5): Dual Transports (stdio/sse), Typer CLI, Packaging (uvx/pipx), and Security Hardening.

For the exhaustive engineering architecture, refer to COLAB_MCP_TECHNICAL_SPECIFICATION.md.


📄 License

Apache License 2.0. See LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers