Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/googlecolab/colab-mcp/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through connecting Gemini CLI — Google’s terminal-based AI agent — to a live Google Colab notebook using Colab MCP. Once configured, Gemini can open a Colab browser session, read and write notebook cells, and execute Python code directly from your terminal conversation.
1

Install uv

Colab MCP is distributed as a Python package and launched via uvx. Install uv using pip:
pip install uv
2

Configure Gemini CLI

Add the Colab MCP server to Gemini CLI’s MCP configuration file. Add the following mcpServers entry:
{
  "mcpServers": {
    "colab-mcp": {
      "command": "uvx",
      "args": ["git+https://github.com/googlecolab/colab-mcp"],
      "timeout": 30000
    }
  }
}
Googlers: If you have a non-standard default PyPI index configured, uvx may fail to resolve the package. Add "--index" and "https://pypi.org/simple" to the args array to force resolution against the public PyPI index:
{
  "mcpServers": {
    "colab-mcp": {
      "command": "uvx",
      "args": ["--index", "https://pypi.org/simple", "git+https://github.com/googlecolab/colab-mcp"],
      "timeout": 30000
    }
  }
}
3

Start Gemini CLI

Launch the Gemini CLI in your terminal:
gemini
Gemini CLI will start and automatically connect to the configured MCP servers, including Colab MCP.
4

Open a Colab connection

Ask Gemini to open a Colab browser connection. For example:
“Open a Colab browser connection”
This prompts Gemini to call the open_colab_browser_connection tool, which generates a unique token, starts a local WebSocket server, and opens a Colab scratch notebook in your default browser.
5

Authorize in the browser

A Google Colab scratch notebook (empty.ipynb) will open in your browser. Wait for it to finish loading and establish the WebSocket connection back to your local server. Once connected, you will see a confirmation message in the terminal indicating the Colab UI is successfully connected.
6

Work with notebooks

Notebook editing tools are now available in your Gemini CLI session. You can ask Gemini to:
  • Run Python code in the connected Colab notebook
  • Read the output of executed cells
  • Write or modify notebook cell content
For example:
“Run a cell that prints the current Python version”
“Read the output of the last cell”

​
Local development setup

If you are contributing to Colab MCP or running it from a local source checkout, use the following configuration instead of uvx. Replace /path/to/github/colab-mcp with the actual path to your local clone: 
{
  "mcpServers": {
    "colab-mcp": {
      "command": "uv",
      "args": ["run", "colab-mcp"],
      "cwd": "/path/to/github/colab-mcp",
      "timeout": 30000
    }
  }
}
This uses uv run to launch the server directly from the local project, picking up any uncommitted source changes automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us