# 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](https://git-scm.com/) and [uv](https://docs.astral.sh/uv/getting-started/installation/).

### macOS or Linux

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

### Windows PowerShell

```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.

## Quick setup for Grok

Prerequisites: [Git](https://git-scm.com/), [uv](https://docs.astral.sh/uv/getting-started/installation/), and the [Grok CLI](https://grok.x.ai/) (`grok` on `PATH`).

```bash
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:

```bash
uv run colab-mcp setup codex grok claude-desktop
```

Or run the steps separately:

```bash
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:

```bash
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](https://research.google.com/colaboratory/faq.html) and the upstream
[CLI session-management design](https://github.com/googlecolab/google-colab-cli/blob/main/docs/01_session_management.md#5-keep-alive-protocol).

### General command example

```json
{
  "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.

```json
{
  "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:

```json
[
  {
    "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:

```bash
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

```bash
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:

```bash
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:

```powershell
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](docs/architecture.md), [security model](docs/security.md),
[error contract](docs/errors.md), [troubleshooting](docs/troubleshooting.md),
[contributing](CONTRIBUTING.md), and
[release procedure](docs/releasing.md). 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