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.

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:

{
  "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, 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.