Skip to main content
Glama

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

colab_session_create

colab new [--session NAME] [--gpu GPU] [--tpu TPU] [--high-mem]

Create a new Colab session

colab_session_list

colab sessions

List all active sessions

colab_session_get

colab status --session <name>

Get session status

colab_session_stop

colab stop --session <name>

Stop (terminate & delete) session

Phase D: Code/File Execution

Tool

CLI Command

Description

colab_code_execute

echo "code" | colab exec --session <name>

Execute Python code via stdin pipe

colab_file_execute

colab exec --session <name> --file <path>

Execute a Python file

Phase E: URL/Log

Tool

CLI Command

Description

colab_session_get_url

colab url --session <name> [--host <host>]

Get browser URL for session

colab_session_log

colab log [--session <name>] [--lines N] [--type TYPE]

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 Tier

Requirements

  • Python ≥3.11 (tested on 3.12.15, 3.15.1)

  • uv package manager

  • Google 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-adapter

OpenCode 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 shell=True

Argument arrays only (subprocess.run(args_list))

No token exposure

Never reads token.json; CLI handles OAuth2

Session ID validation

Regex ^m-s-[a-z0-9-]+$ on all operations

Defensive parsing

Regex with fallbacks, skips [colab] lines

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 CLIResult

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 -v

Project 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


License

MIT

Available Tools

8 tools
colab_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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Local-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.
      59
      9
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to execute Python code on Google Colab GPU/TPU runtimes via the official Colab CLI, with session, file, and package management capabilities.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      42
      61 PyPI
      5
      Apache 2.0