Colab MCP Adapter
Allows managing Google Colab sessions and executing Python code or files within them, including creating, listing, inspecting, and stopping sessions, retrieving session URLs, and accessing session logs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Colab MCP Adapter Create a Colab session with a GPU and run a quick Python sanity check"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Colab MCP Adapter
A local, Windows-compatible stdio MCP server for the Google Colab CLI.
Authentication: Uses the existing Colab CLI OAuth2 flow. The adapter never reads, copies, prints, or modifies CLI credential files.
No GCP/ADC required — wraps the local colab CLI instead of the hosted Colab API.
This adapter is a local interactive-compute integration, not a distributed worker. Google Colab's free managed runtimes prohibit running distributed-computing workers; do not use this adapter as part of a worker pool.
Features (8 Tools)
Phase C: Session Lifecycle
Tool | CLI Command | Description |
|
| Create a new Colab session |
|
| List all active sessions |
|
| Get session status |
|
| Stop (terminate & delete) session |
Phase D: Code/File Execution
Tool | CLI Command | Description |
|
| Execute Python code via stdin pipe |
|
| Execute a Python file |
Phase E: URL/Log
Tool | CLI Command | Description |
|
| Get browser URL for session |
|
| Get session history logs |
Related MCP server: colab-cli-mcp
Architecture
OpenCode v2 (MCP Client)
│ stdio transport (clean JSON-RPC)
▼
Colab MCP Adapter (FastMCP 2.14.7)
│ subprocess (no shell=True)
▼
Colab CLI 0.7.5 (OAuth2 via ~/.config/colab-cli/token.json)
│ HTTPS
▼
Google Colab Free TierRequirements
Python ≥3.11 (tested on 3.12.15, 3.15.1)
uvpackage managerGoogle Colab CLI 0.7.5+ (
uv tool install google-colab-cli)Colab CLI authenticated (
colab login)
Installation
# Clone and install
git clone <repo-url>
cd colab-mcp-adapter
uv sync --extra dev
# Run tests
uv run pytest
# Run server
uv run colab-mcp-adapterOpenCode Integration
For OpenCode v2, add the MCP server to ~/.config/opencode/opencode.jsonc:
{
"mcp": {
"servers": {
"colab": {
"type": "local",
"command": ["uv", "run", "colab-mcp-adapter"],
"cwd": "C:\\Users\\<user>\\Projects\\colab-mcp-adapter",
"timeout": 30000
}
}
}
}OpenCode v2 agents use ordered permission rules. This example allows routine inspection and code execution, while requiring approval for file execution and destructive session termination:
{
"agents": {
"colab-researcher": {
"description": "Conduct computational research using Colab sessions",
"mode": "primary",
"system": "Use existing sessions when possible. Never print secrets. Ask for explicit approval before file execution or stopping a session.",
"permissions": [
{ "action": "colab_colab_session_list", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_session_get", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_session_get_url", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_session_log", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_session_create", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_code_execute", "resource": "*", "effect": "allow" },
{ "action": "colab_colab_file_execute", "resource": "*", "effect": "ask" },
{ "action": "colab_colab_session_stop", "resource": "*", "effect": "ask" }
]
}
}
}These configuration examples target OpenCode v2. OpenCode v1 uses a different configuration schema; use documentation matching the installed version.
Safeguards
Safeguard | Implementation |
No | Argument arrays only ( |
No token exposure | Never reads |
Session ID validation | Regex |
Defensive parsing | Regex with fallbacks, skips |
Error mapping | CLI stderr → MCP codes (404, 409, 408, 401, 429, 500) |
Bounded timeouts | Per-call configurable (1–300s) |
Separate stdout/stderr | Independent capture in |
Destructive stop gated | Explicit warning, termination verified |
Testing
# All tests (71 passing)
uv run pytest
# Protocol tests only
uv run pytest tests/test_stdio_protocol.py -v
# Unit tests only
uv run pytest tests/test_adapter.py -vProject Structure
colab-mcp-adapter/
├── pyproject.toml
├── uv.lock
├── README.md
├── PHASE-B-VERIFICATION.md
├── PHASE-C-VERIFICATION.md
├── PHASE-D-VERIFICATION.md
├── PHASE-E-VERIFICATION.md
├── PHASE-F-VERIFICATION.md
├── RELEASE-MANIFEST.md
├── RELEASE-READINESS.md
├── USAGE-PLAN.md
├── src/
│ └── colab_mcp_adapter/
│ ├── __init__.py
│ ├── __main__.py
│ ├── contracts.py # Pydantic models & error classes
│ ├── parser.py # CLI output parsing
│ ├── adapter.py # Core subprocess wrapper
│ └── server.py # FastMCP server with 8 tools
└── tests/
├── test_adapter.py # 69 unit tests (mocked CLI)
└── test_stdio_protocol.py # 2 protocol tests (real server)Verification Reports
Phase | Report |
B | |
C | |
D | |
E | |
F |
License
MIT
Available Tools
8 toolscolab_code_executeA
Execute Python code in a Colab session via stdin pipe.
Args: session: Session display name code: Python code to execute timeout: Execution timeout in seconds (1-300, default: 30) env: Environment variables to set before execution
Returns: Execution result with stdout, stderr, exit_code, execution_time
Raises: ToolError: SESSION_NOT_FOUND, EXECUTION_TIMEOUT, KERNEL_ERROR, AUTH_EXPIRED, QUOTA_EXCEEDED, CLI_ERROR
Inputs: code (required), session (required), env, timeout. Returns: Result of code/file execution.
colab_file_executeA
Execute a Python file in a Colab session.
Args: session: Session display name file_path: Path to Python file to execute timeout: Execution timeout in seconds (1-300, default: 30) env: Environment variables to set before execution
Returns: Execution result with stdout, stderr, exit_code, execution_time
Raises: ToolError: SESSION_NOT_FOUND, EXECUTION_TIMEOUT, KERNEL_ERROR, AUTH_EXPIRED, QUOTA_EXCEEDED, CLI_ERROR
Inputs: session (required), file_path (required), env, timeout. Returns: Result of code/file execution.
colab_session_createA
Create a new Colab session.
Args: name: Optional session name (auto-generated if omitted) gpu: GPU variant: T4, L4, G4, H100, A100 tpu: TPU variant: v5e1, v6e1 high_mem: Request high-RAM machine shape (requires Pro/Pro+)
Returns: Session info including name, session_id, hardware, shape, variant, status
Raises: ToolError: SESSION_ALREADY_EXISTS, QUOTA_EXCEEDED, AUTH_EXPIRED, CLI_ERROR
Inputs: gpu, tpu, name, high_mem. Returns: Result of session creation.
colab_session_getB
Get status of a specific Colab session.
Args: name: Session display name
Returns: Session info including name, session_id, hardware, shape, variant, status
Raises: ToolError: SESSION_NOT_FOUND, AUTH_EXPIRED, CLI_ERROR
Inputs: name (required). Returns: Result of getting session status.
colab_session_get_urlB
Get the browser URL for a Colab session.
Args: session: Session display name host: Optional Colab frontend host (default: https://colab.research.google.com)
Returns: Full Colab browser URL for the session
Raises: ToolError: SESSION_NOT_FOUND, AUTH_EXPIRED, QUOTA_EXCEEDED, CLI_ERROR
Inputs: session (required), host. Returns: Result of getting session URL.
colab_session_listA
List all active Colab sessions.
Returns: List of sessions with name, session_id, hardware, shape, variant, status
Raises: ToolError: AUTH_EXPIRED, CLI_ERROR
Inputs: no named parameters. Returns: Result of listing sessions.
colab_session_logA
Get session history logs.
Args: session: Session display name (omit to list all sessions with logs) lines: Number of lines to show (default: all) type: Filter by event type (e.g., execution, file_operation, session_created)
Returns: Log lines for the session, or list of sessions with logs if session omitted
Raises: ToolError: SESSION_NOT_FOUND, AUTH_EXPIRED, QUOTA_EXCEEDED, CLI_ERROR
Inputs: type, lines, session. Returns: Result of getting session logs.
colab_session_stopA
Stop (terminate and delete) a Colab session.
WARNING: This is a destructive operation. The session and its kernel state will be permanently deleted. Files in /content persist on the runtime filesystem but the session cannot be resumed.
Args: name: Session display name
Returns: Confirmation that session was terminated
Raises: ToolError: SESSION_NOT_FOUND, AUTH_EXPIRED, CLI_ERROR
Inputs: name (required). Returns: Result of stopping a session.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Session lifecycle tools are clearly separated by action and target, and read-only helpers like get_url and log have distinct purposes. The only mild ambiguity is between code_execute and file_execute, which both execute Python in a session but differ by input form and are clarified in their descriptions.
All tools use snake_case with a consistent colab_ prefix and mostly follow a resource_action pattern. Minor deviations exist: colab_session_log uses only a noun, and colab_session_get_url adds an extra noun to the usual pattern.
Eight tools is well-scoped for a Colab session adapter, covering creation, listing, status, termination, execution, URL access, and logs without obvious padding. Each tool appears to earn its place in the surface.
The core session lifecycle and execution workflows are covered, including logs and browser URL access. Explicit file upload/download or notebook-file operations are absent, though agents can likely work around this by writing files through code_execute.
Maintenance
Related MCP Connectors
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Run any Relay model (image, video, audio, LLM), poll tasks, upload files and search Relay's docs.
Run Python and install PyPI packages from natural language. Hosted at https://cloudish.ai.
Related MCP Servers
- AlicenseBqualityDmaintenanceLocal-first MCP server for controlling Google Colab as a development, shell, file, and training runtime, with tools for notebook editing, GPU acceleration, and file transfer.599Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables MCP clients to execute Python code on Google Colab GPU/TPU runtimes via the official Colab CLI, with session, file, and package management capabilities.-
- AlicenseAqualityCmaintenanceEnables local agents to connect to and interact with Google Colab sessions running in the browser.3Apache 2.0
- AlicenseBqualityBmaintenanceEnables AI agents to drive Google Colab end to end through Google's official Colab CLI: creating and stopping GPU/TPU runtimes, executing code, editing local notebooks cell by cell, launching long background jobs, and uploading or downloading files and folders. Optionally adds opt-in Google Drive tools for signing in, managing project folders, and creating, editing or trashing notebooks, plus mounting Drive on the VM for large datasets.4261 PyPI5Apache 2.0