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.

Colab MCP is an open-source Model Context Protocol (MCP) server that bridges the gap between local AI coding agents and a live Google Colab notebook running in your browser. Traditionally, AI agents have had no reliable way to interact with a running Colab session — reading cell outputs, modifying notebook content, or executing code in the cloud runtime. Colab MCP solves this by acting as a local intermediary: it starts a WebSocket server on localhost, which the Colab frontend connects to, and then exposes the resulting notebook capabilities as MCP tools your agent can call directly.

​
How It Works

The architecture has three cooperating pieces:
  1. Local MCP server — Built with FastMCP, the server starts on your machine and is registered with your MCP client just like any other server.
  2. WebSocket bridge — On startup, a ColabWebSocketServer binds to an ephemeral localhost port and waits for the Colab browser tab to connect. The connection is secured with a one-time token embedded in the notebook URL.
  3. Colab browser session — When your agent calls the open_colab_browser_connection tool, Colab MCP opens a scratch notebook in your default browser. Once that tab loads and handshakes with the local WebSocket server, notebook editing tools are injected dynamically into the MCP tool list.
This design means the heavy computation stays in Colab’s cloud runtime while your local agent drives the notebook through a secure, localhost-only channel.

​
Key Capabilities

  • Dynamic tool injection — Notebook tools are not present at startup; they appear automatically the moment the Colab browser session connects, and disappear if it disconnects. This is powered by FastMCP’s ToolInjectionMiddleware and the MCP notifications/tools/list_changed notification.
  • Single connection model — Only one Colab session may be connected at a time, preventing accidental cross-session interference.
  • Secure token validation — Every WebSocket connection is authenticated with a secrets.token_urlsafe(16) token, so only the intended Colab tab can connect.
  • Configurable logging — Server logs are written to a timestamped file in a temp directory by default, with a --log flag to override the location.

​
Explore the Docs

Quickstart

Install Colab MCP, configure your client, and run your first agent command against a live Colab notebook in under 5 minutes.

Supported Clients

See which MCP clients are compatible and understand the requirements around local execution and tool-change notifications.

Architecture

Dive deeper into the WebSocket bridge, token authentication, and how FastMCP proxy and middleware fit together.

Tool Reference

Full reference for every MCP tool exposed by Colab MCP, including open_colab_browser_connection and the injected notebook tools.
Colab MCP requires an MCP client that supports the notifications/tools/list_changed notification — this is how your agent learns that new notebook tools have become available after the browser connects. The server also binds exclusively to localhost, so your MCP client must be running locally on the same machine. Cloud-hosted or remote agents will not be able to reach the WebSocket server. See Supported Clients for a verified list.

Build docs developers (and LLMs) love

Get started for freeTalk to us