Colab MCP

Give Codex, Grok, Claude, and other MCP clients access to general-purpose Google Colab CPU/GPU runtimes from Windows, macOS, or Linux. The server uses standard MCP over stdio and does not require WSL, SSH, an open Colab browser tab, or Colab Enterprise.

Quick setup for Codex

Prerequisites: Git and uv.

macOS or Linux

git clone https://github.com/anluin/colab-mcp.git
cd colab-mcp
sh scripts/install.sh

Windows PowerShell

git clone https://github.com/anluin/colab-mcp.git
cd colab-mcp
.\scripts\install.ps1

The installer runs colab-mcp setup codex: it creates an isolated environment from the lockfile, completes the one-time Google OAuth flow, and registers the stdio server through Codex's supported codex mcp add command.

Restart Codex after setup, open /mcp, and call colab_health. The ChatGPT desktop app, Codex CLI, and IDE extension share MCP configuration on the same Codex host.

Then give the agent this exact smoke task:

Use Google Colab to start a T4 session named gpu-probe, call colab_inspect, run nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv,noheader with colab_run_command, and call colab_stop in a cleanup step even if the probe fails.

Expected evidence is a non-empty gpu list, a zero command exit code, and a final stopped session.

Related MCP server: Colab MCP

Quick setup for Grok

Prerequisites: Git, uv, and the Grok CLI (grok on PATH).

git clone https://github.com/anluin/colab-mcp.git
cd colab-mcp
uv run colab-mcp setup grok

This authenticates with Google Colab once (if needed) and registers the stdio server through grok mcp add into ~/.grok/config.toml. Grok uses an isolated uv environment so it does not share the repository environment with a long-running Codex or other client session—important on Windows, where a locked console-script entry point can prevent a second uv run from starting.

Restart Grok after setup, open /mcps, and call colab_health (tools appear as colab__colab_health after namespacing). Confirm connectivity with grok mcp doctor colab.

The same CLI can configure multiple clients in one human-run step:

uv run colab-mcp setup codex grok claude-desktop

Or run the steps separately:

uv run colab-mcp auth
uv run colab-mcp install codex
uv run colab-mcp install grok
uv run colab-mcp install claude
uv run colab-mcp install claude-desktop
uv run colab-mcp doctor
uv run colab-mcp doctor --live

Claude Desktop and Grok are registered with an isolated uv environment, so they can update or restart while Codex continues using the repository environment for a long-running session. On Windows, Claude Desktop setup detects both the conventional %APPDATA% configuration and Microsoft Store's virtualized Claude configuration, preferring the active packaged configuration when present.

Only auth and setup may prompt for Google authorization. serve is strictly non-interactive: if credentials expire and cannot refresh, it instructs the human to rerun colab-mcp auth and never launches OAuth inside an agent session. doctor --live performs a read-only assignments API check and reports only the count, never endpoint URLs or tokens.

An existing registration is left untouched. Add --force to an install or setup command to replace it deliberately.

Other MCP clients

Use mcp.example.json as a template, or print ready-to-paste JSON with uv run colab-mcp install json. Run uv run colab-mcp auth once, then configure this server command:

uv --directory /absolute/path/to/colab-mcp run --locked colab-mcp serve

Capabilities

• Create local Colab-ready notebooks.

• Allocate CPU runtimes or T4, L4, G4, H100, and A100 GPUs, subject to account entitlement and availability.

• Execute Python or complete notebooks and preserve Jupyter outputs.

• Run arbitrary programs from argument arrays with a working directory, environment overrides, timeouts, exit codes, separate stdout/stderr, and bounded output.

• Start long-running processes without blocking an MCP request; list, inspect, incrementally read, interrupt, terminate, or kill them in later requests.

• Synchronize complete project and artifact folders within a runtime-owned /content boundary.

• Inspect OS, Python, CPU, RAM, disk, GPU/VRAM, CUDA/driver, requested tools, and a bounded process snapshot without assuming any workload or framework.

• Transfer files or directory trees in bounded chunks with SHA-256 verification, incremental sync skips, staged partials, atomic publication, cleanup, and explicit overwrite limits.

• Upload datasets and download artifacts.

• Pause by checkpointing a notebook and releasing its GPU.

• Resume on a fresh runtime with the same accelerator preference and optionally rerun the notebook.

• Keep active runtimes alive while the MCP server runs.

• Release runtimes explicitly after experiments or errors.

Tools: colab_health, colab_create_notebook, colab_start, colab_sessions, colab_keepalive, colab_run_command, colab_process_start, colab_process_status, colab_process_list, colab_process_output, colab_process_signal, colab_process_export, colab_execute, colab_execute_notebook, colab_allocation_probe, colab_workspace_sync, colab_transfer_cleanup, colab_pause_notebook, colab_resume_notebook, colab_paused_notebooks, colab_reconcile, and colab_stop. Use colab_inspect after allocation to discover the actual runtime rather than assuming that a requested accelerator, executable, or CUDA version is present.

Idle keep-alive

Each tracked assignment gets the upstream CLI's authenticated Tunnel Frontend keep-alive every 60 seconds. The task continues across transient errors, persists its last success/error and consecutive failure count, and is restored from session state when the MCP server restarts. Use colab_keepalive(refresh=true) to send an immediate ping and inspect heartbeat health before an agent begins a long reasoning-only interval.

This refreshes Colab's idle timer; it does not execute synthetic workloads, bypass policy, extend a maximum VM lifetime, reserve an accelerator, or guarantee persistence. Google states that personal Colab idle timeouts and maximum lifetimes vary and runtimes may still be terminated. See the official Colab FAQ and the upstream CLI session-management design.

General command example

{
  "argv": ["python", "-c", "import platform; print(platform.platform())"],
  "session": "compute",
  "cwd": "/content",
  "timeout": 60
}

No shell parses argv. Remote working directories must remain under /content. Each stdout and stderr result is limited to 100 KB by default (1 MB maximum). For longer work, use colab_process_start, then poll status and consume output using the returned next_offset. Process records belong to one runtime and disappear when that ephemeral runtime is released. Each session records a random runtime-incarnation fingerprint both locally and under /content. Every process, filesystem, transfer, and introspection call verifies it before accessing remote state. If Colab recycles an endpoint onto a fresh backend, the call fails explicitly with runtime_replaced instead of reporting Unknown process_id or an apparently empty filesystem; stop the stale session record and start a new runtime. Managed-process metadata is also journaled locally. If its remote record vanishes, process tools return status="lost", the last known argv/cwd/PID/status, and a probable-cause diagnostic such as runtime recycling or OOM. After the first fingerprint mismatch, later file and process calls fail locally without reconnecting to the replacement backend.

colab_process_start can also persist export_on_exit rules. Each rule names one runtime path, one local destination, the matching exit_codes (null means every code; omitted means [0]), whether an existing destination file may be replaced, and bounded transfer limits. A rule may also set compression, compression_min_bytes, and compression_min_savings. A local background watcher polls the owned process independently of agent requests, atomically downloads matching artifacts as soon as the process exits, retries interrupted exports with backoff, and resumes from the process journal after MCP restart. Automatic export never releases the runtime. Inspect auto_export in process status/list results for watching, degraded, completed, or held and per-rule outcomes.

{
  "argv": ["python", "job.py"],
  "session": "compute",
  "export_on_exit": [
    {
      "remote_path": "/content/result.tar.gz",
      "local_path": "./artifacts/result.tar.gz",
      "exit_codes": [0],
      "overwrite": false,
      "compression": "auto"
    },
    {
      "remote_path": "/content/failure.log",
      "local_path": "./artifacts/failure.log",
      "exit_codes": null,
      "overwrite": true
    }
  ]
}

All public MCP input properties carry schema descriptions. Optional fields state their default, units, bounds, selection behavior, or destructive effect directly in tools/list; agents should treat that generated schema as authoritative rather than guessing from parameter names.

In-task worker reload

colab-mcp serve is a stable stdio supervisor. The public colab_connector tool reports the currently loaded worker fingerprint and can replace that worker without closing the MCP connection owned by Codex or Claude. After editing worker code, call action="status", copy available_source_fingerprint, then call action="reload" with it as expected_source_fingerprint. Reload waits for submitted MCP calls, starts a candidate from the fixed source root, completes MCP initialization, verifies the required lifecycle tools and colab_health, and only then switches traffic. Failure leaves the prior worker active.

Reload closes only the old worker's local kernel channels and heartbeat tasks. Persisted assignment, process, and export ownership remains available to the replacement, and remotely durable processes continue. Added or removed MCP tools trigger notifications/tools/list_changed; implementations of existing tools are available immediately. Changes to supervisor.py, dependencies/uv.lock, plugin skills, or the plugin manifest require the normal client/plugin refresh. The supervisor never watches partially written files. Its root is fixed at startup through the installed project or COLAB_MCP_HOT_RELOAD_ROOT. A plugin worker initially installed through uvx may explicitly bind an agent-supplied checkout with source_root; that path is accepted only when local Git identifies its origin as anluin/colab-mcp, and the binding occurs only after candidate validation succeeds.

colab_execute is operation-lease guarded and returns outputs, lease, and timings. Timings separate assignment lookup, kernel connection, kernel preflight, local output processing, retries, and total duration. The upstream kernel client combines request submission, remote execution, and output retrieval into one synchronous interval, which is reported honestly as a combined phase. The remote fingerprint/lease guard duration is measured inside the same request. Kernel channels are cached per runtime and reused across tool calls; timing attempts expose kernel_connection_reused. A harmless preflight validates a cached channel before caller code is sent. Confirmed pre-submission connection failures reconnect and retry once without consuming the operation lease, including for process start. Unknown post-submission outcomes are never retried. Every command is runtime-owned and receives a process_id. The timeout is only how long the MCP call waits: if it expires, process_continues=true and the command remains alive for later status/output/signal calls. Termination is always explicit. Python/Jupyter output is bounded to 100 KB by default (1 MB maximum) and ends with an explicit truncation marker. Detached processes retain at most 10 MB per output stream by default (configurable up to 1 GB with output_limit). They continue draining excess output so the child cannot deadlock; output reads return truncated=true when retained output was capped. While a process is running, stored_bytes and total_bytes reflect the durable spool currently available to readers; total_bytes_final=false marks that live lower bound. After exit, total_bytes is the complete byte count, including discarded bytes, and total_bytes_final=true. The handoff deadline is best-effort because each Colab kernel status/output round-trip has latency; it is not a hard real-time deadline.

colab_workspace_sync is the only public general file-transfer tool. It accepts purposeful local and remote directory roots with direction="push" or direction="pull". Agents should build a temporary staging directory containing only the run's required files—never naively select a whole repository, home directory, environment, cache, or mixed output tree. Push computes one remote manifest, packs only changed files into a deterministic bundle, transfers that bundle in bounded resumable chunks, verifies every declared path, size, and SHA-256 value before publication, and atomically replaces each changed file. A no-change push needs one remote round trip. Destination-only files are never deleted. Pull retains the bounded per-file recovery path. The underlying transfer engines remain private so agents cannot shuttle individual bytes or mutate arbitrary runtime files through MCP. Transfers use gzip when the measured bundle or file is at least 10% smaller. Set compression="gzip" to force gzip or compression="none" to send original bytes. Original and wire SHA-256 values are verified, and results distinguish logical total_bytes from wire_bytes. In auto mode, already-compressed image, audio, video, and archive formats bypass the expensive gzip trial pass. colab_workspace_sync is the single supported upload/download API; its direction selects push or pull while process export remains a lifecycle-specific operation. Explicit diagnostics can use an end-to-end encrypted WebRTC data channel after the guarded kernel connection installs a pinned, checksum-verified endpoint script in the owned runtime. ICE signaling remains inside the authenticated kernel channel; file bytes then travel directly between peers, or through an explicitly configured TURN relay. The endpoint revalidates the runtime incarnation and operation lease before and after transfer. SHA-256 verification, resumable staging, size/file-count bounds, and atomic publication are identical for every transport.

transport="auto" is the default reliable path. Uploads use native binary kernel-websocket buffers; bulk downloads use concurrent authenticated HTTP byte ranges, with per-range bounds and a final SHA-256 check before publication. It does not first attempt a topology-dependent transport or silently fall back. Use transport="webrtc" only to require and diagnose the peer path; transport="kernel" is an explicit alias for the authenticated path. Results report data_transport and per-file transport values.

The default ICE configuration uses public STUN for discovery only. Production TURN requires your own short-lived authenticated credentials; no open relay credentials are embedded. Configure a bounded JSON list in COLAB_MCP_WEBRTC_ICE_SERVERS, for example:

[
  {
    "urls": ["turns:turn.example.com:5349?transport=tcp"],
    "username": "temporary-user",
    "credential": "temporary-password"
  }
]

COLAB_MCP_WEBRTC_MIN_BYTES changes the auto threshold (default 4194304). COLAB_MCP_WEBRTC_LANES enables 1-16 parallel peer associations (default 1); extra lanes should be benchmarked because they can reduce throughput on small or CPU-constrained runtimes. TURN credentials cross only the authenticated kernel signaling channel, are handed to the endpoint in an owner-readable launch file that is removed on startup, and are never returned or logged.

Run the opt-in end-to-end acceptance outside MCP with a dedicated runtime:

uv run python scripts/live_p2p_acceptance.py --size-mib 32 --transport webrtc --lanes 1

The harness reports allocation, push, pull, hash verification, and release phases. It uses an isolated session/state root and releases the runtime in finally; after interruption, audit account assignments before deleting recovery state.

An optional positive include list selects relative POSIX-glob paths after mandatory exclusions for VCS data, environments, caches, and common secret-key files. Each sync computes the verified content-hash delta internally and transfers only changed files in a single call.

colab_allocation_probe returns an opaque, one-hour lease_token bound to the tracked endpoint and runtime fingerprint both locally and inside that runtime. Pass it to a transfer or process start to avoid a new probe. Critical remote requests validate the token and fingerprint in the same Python request before mutation, so the operation cannot follow a replacement runtime. Omitting the token performs a fresh probe. Assignment lookup is bounded to five seconds and reports assignment_no_longer_exists or assignment_lookup_timed_out separately. Probe observations do not wait for Colab's slow Tunnel Frontend heartbeat endpoint; the existing background keepalive continues independently and the result reports heartbeat="background".

Uploads emit MCP progress after every durable chunk with phase, bytes, total, chunk number, and elapsed time. A failed upload reports its transfer_id, deterministic staging_path, known staged offset, submission state, and whether same-incarnation resume is safe. Retry with the same transfer_id; the server verifies the staged prefix before continuing. Successful publication removes staging. Failed staging is retained for resume and can be explicitly removed with colab_transfer_cleanup.

After an owned process exits, colab_process_export downloads one file or directory into a hidden sibling staging path and publishes it locally with one filesystem rename. Any status, lease, transfer, checksum, publication, or release failure returns disposition="held" and leaves the runtime tracked. release_on_success=false is the safe default; setting it to true releases compute only after publication succeeds. Atomic overwrite of an existing directory is intentionally unsupported across platforms—export to a new destination instead.

The sibling stage is deterministic for the process, remote path, and local destination. A retry reuses it and checksum-skips files already completed, so multi-file exports resume at file granularity across MCP restarts. Failed results include a recoverable_export record and preserve the stage; successful publication removes it. colab_process_export_cleanup explicitly discards a stage that will not be resumed.

Crash recovery and orphan cleanup

Allocated endpoints are persisted before runtime preflight, so even a double failure during startup remains recoverable. colab_reconcile compares persisted sessions with the account's live Colab assignments. Its default is read-only: it reports stale local records and live orphan endpoints. Pass forget_stale=true to remove records whose runtime is already gone. Pass release_orphans=true only when you intend to release every live assignment not owned by this colab-mcp state directory. Failures are returned per endpoint for safe retry. colab_stop is idempotent when a tracked runtime has already disappeared.

Recommended agent lifecycle

1. Check colab_health.

2. Start with a T4 unless another accelerator is required.

3. Build a temporary local source snapshot containing only required tracked source, configuration, and private inputs; fetch public datasets and model weights directly on Colab. Never sync the repository root, VCS metadata, caches, environments, or historical outputs.

4. Sync the focused source snapshot in one call. Push to /content/workspaces/<task>/source and write results only under the sibling /content/workspaces/<task>/artifacts directory.

5. Create or execute a notebook or durable process.

6. Pull only the artifact folder with colab_workspace_sync.

7. Pause to checkpoint and release compute, or stop when finished.

8. Always stop a runtime after an error if it was not already released.

Pause and resume semantics

Colab does not expose a supported suspended-VM or runtime-snapshot operation. Pause records the local notebook checkpoint and accelerator preference, then releases the runtime. Resume allocates a new runtime and can rerun the notebook.

RAM variables, ad-hoc package installs, and files left only in /content do not survive. Put installation commands in the notebook and download checkpoints before pausing.

Agent workflows and self-repair

The Codex plugin includes focused skills for short/durable runtime operation, whole-folder sync, and connector repair. The repair workflow targets https://github.com/anluin/colab-mcp and uses GitHub CLI exclusively for GitHub network access. If gh is absent, the agent must stop and ask whether the user wants it installed; it must not silently substitute another downloader or API client.

Free, Pro, Pro+, and Pay As You Go personal accounts are supported. Actual GPU models, runtime length, and compute usage remain controlled by Google Colab.

Security

This MCP executes arbitrary Python and can consume the authenticated account's quota. Keep it as a local stdio server and connect only trusted clients. OAuth and runtime proxy tokens are never returned through MCP tools.

Session state defaults to ~/.config/colab-mcp. Override it with COLAB_MCP_STATE_DIR. Set COLAB_MCP_AUTH=adc only if you deliberately configured Google Application Default Credentials with the required Colab scopes.

Operational logs are single-line JSON on stderr so MCP stdout framing remains clean. Configure the threshold with COLAB_MCP_LOG_LEVEL. Graceful server shutdown cancels only local keep-alive tasks; it deliberately preserves owned assignments/processes for restart recovery. Use colab_stop or colab_reconcile for explicit quota release.

Development and validation

uv sync --locked --dev
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv run --with bandit bandit -q -lll -r src scripts
uv run --with pip-audit pip-audit
uv build
uv run twine check dist/*

CI runs on Ubuntu, macOS, and Windows with Python 3.12. The live integration has also been verified against a real Tesla T4: allocation, CUDA execution, notebook execution, pause/release, fresh-runtime resume, rerun, and cleanup with zero assignments remaining.

The public workspace-sync probe exercises nested multi-file push, incremental changed/new/unchanged selection, multi-chunk binary transfer, destination-only preservation, mandatory VCS exclusion, pull-back SHA-256 verification, and runtime cleanup:

uv run python scripts/live_workspace_probe.py

The opt-in durability acceptance harness reproduces the large Windows/Codex workload with either accelerator. Defaults deliberately consume about five minutes of runtime and transfer two verified copies of twenty 1.9 MB checkpoint files, so run it only when that quota use is intended:

uv run python scripts/live_acceptance.py --accelerator T4
uv run python scripts/live_acceptance.py --accelerator L4

It performs a three-observation lease probe, guarded CUDA check, 63 KiB and incompressible 1.9 MB uploads with progress, durable process start, manager/server-lifespan restart, watcher recovery, automatic export, SHA-256 verification, and a second atomic export with release_on_success=true. Every phase is a named --fail-after injection boundary; cleanup in finally reacquires persisted ownership after the simulated server stop before releasing the assignment.

The Google Colab integration version is pinned to the live-tested release. This project imports its portable client components; it does not invoke the platform-limited CLI executable.

Further documentation: architecture, security model, error contract, troubleshooting, contributing, and release procedure. Version history and readiness evidence live in Git tags, commits, and GitHub release notes rather than duplicated version-specific repository files.

Upstream projects

• https://github.com/googlecolab/google-colab-cli

• https://github.com/googlecolab/jupyter-kernel-client

• https://github.com/modelcontextprotocol/python-sdk

Codex registration follows OpenAI's documented MCP flow: https://learn.chatgpt.com/docs/extend/mcp