colab-mcp: a local agent driving a Colab session in the browser

The session is in the browser, the agent is on your desk

The one-line description is that colab-mcp is an MCP server for bridging your local agent to a Colab session in the browser, and everything about the design follows from that split.

A coding agent normally runs where your code is. If you want it to work against a Colab session, the usual options are to have the agent shell out to some remote execution path, or to give it a way to talk to the notebook runtime directly. colab-mcp is the second: it is a Model Context Protocol server, so the agent talks to it over the standard MCP tool interface, and the server in turn talks to the Colab session.

The value of that arrangement is that the expensive, awkward part stays in the browser tab. A Colab session has its own runtime, its own libraries and its own machine characteristics, and driving it from an agent running on a laptop means the agent is not pretending to have a GPU it does not have.

The dependency list supports that reading. The package depends on fastmcp, the mcp package with the cli extra, websockets, google-auth-oauthlib and requests-oauth2client for talking to Google, and jupyter-kernel-client for the notebook side. The Colab session is a Jupyter kernel, and the server drives it as one.

Two client requirements that decide whether it works at all

The README states the requirements in one line, and it is worth reading twice because the first one is unusual. The MCP server requires client support for notifications/tools/list_changed, and it requires the client to be running locally on your device.

The list_changed notification is a mechanism for the server to tell the client that its set of tools has changed. A server whose tool list can change during a session, which is exactly what a bridge to a Colab session needs, since what can be done depends on what the notebook has, cannot be described once at startup and left alone.

The local requirement is the second half, and it rules out hosted agents. The server reaches a browser session, and the reasoning about how that connection is established depends on the agent being on the same machine as the user, in the same way that a browser extension bridge does.

The README names the clients that fit. Gemini CLI, Claude Code and Windsurf are listed as popular options, and the phrase used is clients that fit these criteria, which leaves the door open for others that meet the same bar.

So the first thing to check before anything else is whether your agent satisfies both conditions, because a server that cannot negotiate a changing tool list will simply not be usable with it.

Setup is uv, then an entry in the client configuration

The setup has two parts. You install uv, with pip install uv, and then you configure the server in whatever file your client uses, the README giving the mcp.json style as the example:

"mcpServers": {
  "colab-mcp": {
    "command": "uvx",
    "args": ["git+https://github.com/googlecolab/colab-mcp"],
    "timeout": 30000
  }
}

The interesting details are the command and the timeout. The command is uvx, which runs a tool straight from a source reference without a separate install step, and the argument is the git URL of the repository, so the client fetches the server itself at launch. The timeout of 30000 is in milliseconds, so thirty seconds, and it exists because the first run has to resolve and build the package rather than start a prebuilt binary.

One note targets a specific audience. If you use a non-standard default package index, which the README calls the Googler situation, you may also need to add --index https://pypi.org/simple, since the server has to be resolvable from a public index.

The developers themselves run it differently, from a checkout, with the uv command and a run argument, a working directory and the same thirty-second timeout:

"mcpServers": {
  "colab-mcp": {
    "command": "uv",
    "args": ["run", "colab-mcp"],
    "cwd": "/path/to/github/colab-mcp",
    "timeout": 30000
  }
}

The internal setup also asks for the git hooks to be enabled, with git config core.hooksPath .githooks, so that the presubmit checks run before a commit.

The Python side and what it pins

The package metadata is small and reveals the shape of the project. The name is colab-mcp, the description is an MCP server for Colab, and the build backend is hatchling with a console script colab-mcp pointing at colab_mcp:main.

The runtime requirements are pinned more tightly than the metadata of most tools. fastmcp is pinned to exactly 2.14.5, mcp with the cli extra is at 1.20.0 or newer, pydantic is bounded below by 2.12.3 and above by 3.0.0, and websockets, anyio and requests are all constrained. Python 3.13 or newer is required, which is a high floor and tells you this is a new project rather than a port of something older.

The development group is equally conventional for a modern Python project: pytest with pytest-asyncio for the async tests, pytest-cov and coverage for measurement, ruff for linting, and a separate commit group for pre-commit. The repository also carries a.pre-commit-config.yaml, a.python-version file, a uv.lock for reproducible resolution, and a tests/ directory beside src/.

There is a commented block in the pyproject.toml for local development with jupyter-kernel-client, pointing at a sibling checkout, and an explicit uv index entry for the public PyPI simple index, which matches the note about non-standard indexes in the README.

Discussions instead of issues, and no external pull requests

The project has an unusual and clearly deliberate contribution policy, and it is stated without much hedging. For issues and feature requests, the README says GitHub discussions are used as the place for issue discussion and feature requests, and that as discussions mature into action items, those items will be added as issues. The stated reason is to make sure that issues in the issue tracker are well-understood, deduplicated and actionable. It ends with a request not to open issues directly.

For contributions, the message is blunter. The README says they do not have the bandwidth to support review of external contributions, and they do not want user pull requests to languish, so external contributions are not being accepted right now. The invitation is to bring ideas and pain points to the discussions page instead.

That is a defensible position for a project that a team at Google maintains alongside its product, but it is a real constraint for anyone who wanted to contribute a fix. It also shapes how you get help: the answer is a discussion thread, and the answer to a question may arrive as an issue later, or as a change to the code, or not at all.

Where colab-mcp is the wrong tool

The first wrong-tool case is a local environment. If the code is on your machine and you want an agent to work on it, a local agent with a local interpreter is simpler, faster and has fewer moving parts. The reason to reach for this server is the Colab session specifically, and if there is no Colab session in the picture then the server adds a protocol hop and a browser dependency for nothing.

The second is a client that does not meet the requirements. The list_changed support and the local requirement are stated as requirements rather than preferences, and a client that fails either is simply not compatible. Any agent hosted in a cloud service, where the agent is not running on your device, is excluded by the second condition, and that is a large and growing category of tools.

The third is a team that wants to contribute upstream. The project is not accepting external pull requests, so a team that needs a change, a feature or a fix has to go through a discussion and hope. For an internal fork that is fine, since you can take the code and change it, but it does mean the upstream is not a route to a feature you need.

One more practical point is the version floor. Python 3.13 or newer is required, and a fleet of older interpreters in a research group or a teaching environment is an obstacle that the uvx based setup does not remove.

Apache-2.0, three releases in March 2026, and a quiet patch line

The project is licensed under the Apache License 2.0, with the LICENSE file at the repository root, and the repository is not archived.

The release history is short. v1.0.0 was released on 2026-03-19, v1.0.1 on 2026-03-27 and v1.0.2 on the same day a few hours later. Three releases in eight days, all in the 1.0 line, and then the last push was on 2026-06-23, with no release tag since March. That is the shape of a project that reached a stable 1.0 quickly and has been maintaining it since.

It is also a young project by any measure, and the README is written accordingly, with the setup instructions, the internal developer section and a support policy that explicitly limits external contributions.

The two things worth carrying forward are the client requirements, since they decide whether the tool works for you at all, and the fact that the server is fetched from the git repository by uvx at launch. The second has a pleasant consequence: there is no version pinning in the client configuration to keep up to date, and an unpleasant one, in that the code you run is whatever is on the default branch of the repository at that moment, rather than a published release you chose. For a bridge into a session that may hold credentials and a paid GPU runtime, that is worth thinking about before you wire it into a daily workflow.

Editorial conclusion

Adopt colab-mcp if you want an agent to work against a real Colab session, with its GPU runtime and its browser-based workflow, from an agent that runs on your own machine. Do not adopt it if your client does not support notifications/tools/list_changed or if you need the agent to run against a local environment, since a local interpreter is simpler and the whole point of this server is the remote browser session. Before you configure it, check that your client meets the stated requirements, expect the setup to depend on uv being present, and note that the project is not accepting external pull requests, so your route to a change is a discussion rather than a patch.

Frequently asked questions

Official sources

1. googlecolab/colab-mcp on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases