← All projects

Colab-MCP: an AI agent that runs Google Colab

Unofficial MCP server that lets an AI agent start a machine on Google Colab, run a job, watch it and shut it down, without the model ever seeing credentials. It wraps the official Colab CLI. Published on PyPI: install it with uvx colab-cli-mcp. Validated with tests against a simulated CLI and one live run: 10 videos, 6.7 GB, 0 errors.

Colab-MCP: an AI agent that runs Google Colab

Purpose

Let an AI agent use Google Colab, GPU included, end to end and without manual intervention at every step.

What it solves

Running a job on Colab takes manual steps: start the machine, upload files, run cells, wait and shut down. An agent has no interactive terminal and should not handle Google credentials either.

How it works

An MCP server that wraps the official Colab CLI. Google permissions are approved by the person in the browser; the model never sees passwords, codes or tokens. Local paths are confined to one folder, there is no shell, and deletion sends files to a trash folder.

Scope

  • Starts and stops Colab machines, runs jobs and watches them.
  • Uploads and downloads files, and mounts Google Drive with its own pseudo-terminal.
  • Permissions are approved by the person; the model receives no credentials.
  • Local paths confined to one folder; deletion goes to a trash folder.

Limitations

  • Unofficial; no relation to Google.
  • A single live run; timings and success rate were not measured.
  • Tested only on macOS and with Claude.
  • The Drive tools were tested against a simulated API.
  • With Drive mounted in the virtual machine, code running there can read the whole Drive.
  • Published on PyPI as version 0.1.0, Alpha status. That version cannot be replaced: a fix ships as 0.1.1.

Costs

Build and testing time
1 day (about 2 hours of testing)
Claude session usage (Sonnet 5.5)
10% to 15% (estimate; tokens were not measured)

Verified result

10
videos processed in the live run
6.7 GB
of data in that run
0
errors in that run

How it was tested

Testing something that depends on a person’s Google account was solved in three layers:

  1. A simulated Colab CLI that runs the real code, with no account and no network.
  2. A real MCP client connected to the server, the way Claude would use it.
  3. A live run with a real job.

The first two layers show the code does what is expected; they do not show that Google responds the same way. That is what the live run is for.

Possible use cases

So far it has been used in one case. What follows are possibilities, not results.

  • Academia. A course where each student asks for a GPU without owning one; an agent that runs the class notebooks and returns results.
  • Research labs. Repeat an experiment with different seeds and collect the results the next day; compare models on the same test set.
  • Big data and intelligence. Process large batches of text, audio or video with a model and leave the results organized in Drive.
  • Ambitious cases. An agent that takes a research question, designs the experiment, runs it on a GPU, reads the results and adjusts it. Automatically reproducing the experiment of a scientific paper. Evaluating every new model as soon as it is released.

None of these cases has been tested.

Next use

It will be used in a separate experiment: testing 6 models, one of them Gemma, an open-weight model. That has not been done yet, so there are no results.

How it was published on PyPI

The server used to live only on GitHub: to use it you had to clone the repository and set up paths by hand. Now it is a package on PyPI, the official catalog of Python packages, and it runs without cloning anything.

  1. The package was prepared: name, license, version 0.1.0, description and README.
  2. A GitHub workflow was created that tests the code, builds the package and uploads it.
  3. It was rehearsed first on TestPyPI, a practice copy of PyPI.
  4. It was published on the real PyPI with the v0.1.0 tag.
  5. It was installed from PyPI and verified to start with its 42 tools.

Publishing uses Trusted Publishing: PyPI only accepts releases from the amgallego8/Colab-MCP repository, with that workflow and with an environment approved by its author. That is why no password or token is stored in GitHub. Future releases go through the tests and that approval.

Being on PyPI does not mean it has users or that it is validated live for everything it promises. Its status is Alpha and the README lists the parts that were not tested.

Install

uvx colab-cli-mcp

You can also install it with pip install colab-cli-mcp, or by cloning the repository:

git clone https://github.com/amgallego8/Colab-MCP ~/Colab-MCP && cd ~/Colab-MCP
bash install.sh

Links

Collaborations

Projects, research or ideas worth building together.

info@angelgallego.comWrite to me →