colabmcp
Bridges AI agents with consumer Google Colab to run Python code and Jupyter notebooks on cloud runtimes. Provides tools to provision and switch runtimes (CPU, NVIDIA GPUs, TPUs, high-RAM shapes), re-attach to existing sessions, execute code or entire .ipynb notebooks cell-by-cell through the Jupyter messaging protocol, capture interleaved stdout/stderr and Matplotlib/Seaborn visualizations as multimodal content, keep runtimes alive or auto-unassign idle ones, and save executed notebooks back to disk.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Google Colab MCP Server (colabmcp)
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=Nquery parameters andX-Goog-AuthUser: Nheaders.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 logincredentials.Chrome CDP Fallback: Real Chrome automation via Chrome DevTools Protocol with subprocess
DEVNULLstdout 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 invokesunassign_runtimeafter 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_headersforwebsocketsv13+/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
ImageContentandTextContentblocks, 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 innb.cells), optional kernel reset before run, structured failure diagnostics (error_name,error_value,traceback), and save notebooks back to disk usingnbformatv4.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, andFREE_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 chromium2. 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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:
colabTransport:
stdioCommand:
colab-mcpArguments:
["run"]
🔑 Authentication Guide
Before provisioning runtimes, authenticate your Google account using one of the following methods:
Method A: Remote OAuth 2.0 Flow (Recommended for CLI & Agents)
Ask your agent to call
colab_login(method="oauth_remote")or run in terminal:colab-mcp login --method oauth_remoteThe server outputs a Google authorization URL. Open the link in any browser, log in with your Google account, and grant access.
Copy the resulting authorization code from
https://sdk.cloud.google.com/applicationdefaultauthcode.html.Provide the code back to the agent or paste into the terminal prompt.
Tokens are securely encrypted into your OS Keyring.
Method B: Local Loopback OAuth (Desktop Environments)
colab-mcp login --method oauth_loopbackSpawns 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_browserLaunches 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 |
|
| Authenticate with Google Colab and store encrypted credentials in OS keystore. Supports multi-account user indexing. |
|
| Query active account identity, token validity, and Colab Compute Unit (CCU) balance. |
|
| Wipe stored credentials from OS keystore and optionally terminate cloud runtimes. |
2. Runtime Management Tools
Tool Name | Parameters | Description |
|
| Query available accelerators (CPU, T4, L4, A100, TPU), RAM shapes, and hourly compute unit costs. |
|
| List all active remote and locally tracked Colab VM sessions (including browser or prior-run sessions) and live kernel states. |
|
| Provision or re-attach to a Colab container VM and initialize kernel WebSocket. Re-attaches to active matching sessions ( |
|
| Check VM health, live CPU/RAM/VRAM/disk utilization, kernel state, and idle timer. |
|
| Release one or all local/remote Colab VMs via |
3. Execution & Output Monitoring Tools
Tool Name | Parameters | Description |
|
| Execute Python code snippet; returns chronological multimodal content ( |
|
| Execute complete |
|
| Poll execution progress, elapsed time, and partial stdout for asynchronous jobs. |
|
| Retrieve full buffered outputs in strict chronological kernel emission order for an execution ID. |
|
| Dispatch SIGINT interrupt; escalates to kernel restart if unhalted within 5.0s. Returns |
⚡ 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 |
| 2 vCPU Intel Xeon | None | ❌ Pro/Pro+ only (Not on Free Tier) | ✅ Yes | 0.00 CCU/hr |
| NVIDIA Tesla T4 | 16 GB GDDR6 | ❌ Pro/Pro+ only (Not on Free Tier) | ✅ Yes (Dynamic) | ~1.96 CCU/hr |
| NVIDIA L4 Tensor Core | 24 GB GDDR6 | Supported | ❌ Pro/Pro+ | ~3.84 CCU/hr |
| NVIDIA A100-SXM4 | 40 GB / 80 GB | Supported | ❌ Pro/Pro+ | ~5.42 - 11.2 CCU/hr |
| NVIDIA H100-SXM5 | 80 GB HBM3 | Supported | ❌ Pro+ | ~13.50 CCU/hr |
| Cloud TPU v5e | 16 GB HBM | Standard Shape | ❌ Pro/Pro+ | ~1.96 CCU/hr |
| Cloud TPU v6e | 32 GB HBM | Standard Shape | ❌ Pro+ | ~4.50 CCU/hr |
Important Note on Free Tier Restrictions:
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).Free Tier allows only 1 concurrent GPU container VM.
colab_connect_runtimedefaults toreuse_existing=Trueto query active sessions viaGET /tun/m/assignmentsand re-attach rather than attempting duplicate allocations that trigger HTTP 412 (TooManyAssignmentsErrororFreeTierQuotaExceededError).
🛡️ Security Architecture
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.Encrypted Storage: Secrets are managed via OS-native vaults (Windows DPAPI, macOS Keychain, Linux Secret Service). Headless servers utilize AES-256-GCM encryption with
0600file permissions.Execution Sandbox: All code execution occurs inside Google's cloud containers. No arbitrary code is evaluated locally on the host machine.
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.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.CDP Subprocess Stdout Isolation: Chrome automation launches with
stdout=subprocess.DEVNULLandstderr=subprocess.DEVNULLto prevent browser diagnostics from corruptingstdioJSON-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 (
nbformatv4 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Related MCP Servers
- AlicenseDqualityDmaintenanceEnables agents to control Google Colab notebooks through a secure, headless WebSocket architecture, allowing cell creation, editing, execution, and inspection without browser automation.133Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to autonomously manage Google Colab GPU sessions, submit and monitor training jobs, and debug/fix issues via an encrypted tunnel without requiring a browser tab.MIT
- FlicenseNot gradedqualityDmaintenanceConnects Claude Desktop to a Google Colab runtime via ngrok for remote Python execution, enabling GPU/CPU code execution with smart timeouts and file management.1-
- AlicenseBqualityCmaintenanceLets any MCP-compatible agent use Google Colab or Jupyter runtimes as an execution backend, enabling code execution, notebook management, package installation, hardware introspection, training jobs, and file handling.401MIT