Quickstart: Run Your First Colab MCP Agent Session

This guide walks you through everything needed to go from zero to a live AI agent session connected to a Google Colab notebook. By the end you will have Colab MCP installed, your MCP client configured, and a working agent that can read and edit a Colab notebook running in your browser.

Install uv

Colab MCP is distributed as a Python package and launched via uvx, so uv must be installed on your machine before anything else.

pip install uv

uv is a fast Python package manager and runner. The uvx command it provides lets MCP clients launch Colab MCP on demand without a manual install step.

Configure your MCP client

Add the following entry to your MCP client’s configuration file (commonly mcp.json or claude_desktop_config.json, depending on your client):

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

This tells your client to fetch and run Colab MCP directly from GitHub using uvx. The timeout value of 30000 ms gives the server enough time to start up before the client considers it unavailable.

If your machine uses a non-standard default Python package index — for example, if you are a Googler on an internal network — add "--index", "https://pypi.org/simple" to the args array so that uvx resolves dependencies from the public PyPI index:

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

Start your MCP client

Launch your MCP client — Claude Code, Gemini CLI, Windsurf, or any other supported client. The client will read your configuration and start the Colab MCP server process automatically in the background.At this point the server is running, but no notebook tools are available yet. Only the open_colab_browser_connection tool is exposed until a Colab browser session connects.

Connect to Colab

Ask your agent to call the open_colab_browser_connection tool. For example:

Please open a Colab browser connection.

The server will open a Colab scratch notebook (https://colab.research.google.com/notebooks/empty.ipynb) in your default browser, with an authentication token embedded in the URL. Wait for the notebook tab to fully load — once it does, it handshakes with the local WebSocket server and the connection is established.The agent receives a boolean result: true if the connection succeeded within the 60-second timeout, false otherwise. If it times out, simply reload the browser tab or try again.

Use notebook tools

Once the Colab session is connected, notebook editing tools are injected into the MCP tool list automatically via a notifications/tools/list_changed notification. Your agent now has access to tools for interacting with the live notebook.Try asking your agent something like:

Add a code cell that prints "Hello from Colab MCP!" and run it.

The agent will use the newly available notebook tools to create the cell, execute it, and read back the output — all without you touching the notebook manually.

By default, Colab MCP writes timestamped log files to a temporary directory (e.g. /tmp/colab-mcp-logs-XXXXX/colab-mcp.YYYY-MM-DD_HH-MM-SS.log). To write logs to a specific location, pass the --log flag with a directory path in the args of your MCP configuration:

"args": ["git+https://github.com/googlecolab/colab-mcp", "--log", "/path/to/your/logdir"]

Logs are useful for debugging connection issues or inspecting the raw MCP message flow.

Not all MCP clients are compatible with Colab MCP. The server requires clients that support notifications/tools/list_changed and run locally on your device. See Supported Clients for a verified list of compatible clients.

Get Started

How It Works

Configuration

Guides