`colab-mcp` lets an mcp client use google colab runtimes: launch one, run
python, read and write files, and stop it when you're done.

## installation

requires node 22 or newer.

```sh
git clone git@knot.gaze.systems:did:plc:66oo2mns5n6jfbjridin6vjj colab-mcp
cd colab-mcp
npm ci
npm run login
```

login opens google in your browser and receives the redirect automatically; no
code to paste. credentials stay in `~/.config/colab-mcp/credentials.json`, and
access tokens refresh automatically. on a headless machine, use
`npm run login -- --manual` for the explicit code-paste fallback.

if you'd rather have a standalone binary, install bun and run `npm run build`.
it writes `dist/colab-mcp` for your current platform.

## setup

add this to your mcp client's config, using your checkout's absolute path:

```json
{
  "mcpServers": {
    "colab": {
      "command": "node",
      "args": ["/path/to/colab-mcp/src/index.js"]
    }
  }
}
```

for the standalone binary, use its absolute path as `command` and omit `args`.
run `./dist/colab-mcp login` to sign in.

## hosted server

an optional oauth gateway is included in `gateway/`; it handles mcp client
registration, owner login, consent, and google account connection. build it with
`npm run build:gateway` (go 1.26.2+), configure the [hosted setup](gateway/README.md),
then run `npm run serve`. mcp clients use your server's `/mcp` url.

google's bundled desktop client cannot redirect to your server. hosted browser
login needs your own google web-app client configured once; afterwards the
owner connects google in the browser, without copying refresh tokens or codes.

hosted login supports up to 16 google accounts. `colab_accounts` exposes stable random
account ids, not emails; the model chooses an `account_id` for launches and usage.
runtime handles keep operations pinned to their owning account. add or remove accounts
on the owner-only connection page; quotas remain separate, with no automatic failover.

you can still set `COLAB_CREDENTIALS` to an existing google authorized-user json
file. it needs a refresh token with colab access; the file is never modified.

all tools advertise `readOnlyHint: true` by convention, but they can execute code,
modify files, and allocate paid compute. stop runtimes when you're done; closing
the mcp client doesn't stop them.