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 acts as a bridge between a locally running AI agent and a live Google Colab notebook open in your browser. At a high level, your MCP client sends standard MCP tool calls to the colab-mcp FastMCP server running on your machine. That server relays the messages over a local WebSocket connection to the Colab browser session, which handles the actual notebook execution and returns results back through the same path. The entire communication chain — from agent to notebook — happens over localhost WebSocket tunneling, with the browser as the real notebook runtime.

​
Three-Layer Architecture

MCP Client

Tools like Claude Code, Gemini CLI, or Windsurf speak the Model Context Protocol directly to colab-mcp. They discover tools, call them, and receive results — unaware of the browser layer beneath.

Colab MCP Server

A FastMCP server that receives tool calls, runs middleware, and proxies requests to the connected Colab session. It also injects the open_colab_browser_connection tool into every MCP response.

Colab Browser Session

The Google Colab UI running in your browser connects back to the local server over WebSocket. It acts as the real notebook runtime — executing code, managing cells, and returning results.

​
Data Flow

MCP Client  ←→  colab-mcp (FastMCP)  ←→  WebSocket  ←→  Google Colab (browser)
Every tool call from the MCP client travels right to left: the client sends an MCP JSON-RPC request to colab-mcp, the server forwards it over the local WebSocket to the Colab browser session, Colab executes the request and sends back a response, and the server returns that response to the client.

​
Startup Sequence

1

WebSocket server starts and token is generated

When colab-mcp starts, ColabSessionProxy.start_proxy_server() is called. This brings up a ColabWebSocketServer bound to localhost on a randomly assigned port (port=0 lets the OS pick a free port). During construction, the server generates a one-time URL-safe token via secrets.token_urlsafe(16) that it will require for all incoming connections. The assigned port is available as server.port after the context manager enters.
2

ColabProxyClient and FastMCPProxy are created

A ColabProxyClient is started against the new WebSocket server. It immediately fires a background task (_start_proxy_client) that blocks until a Colab browser session connects. A FastMCPProxy is then created with client_factory=proxy_client.client_factory and the instructions string "Connects to a user's Google Colab session in a browser and allows for interactions with their Google Colab notebook", so all proxied tool calls are routed dynamically based on connection state.
3

Middleware is registered in order

Two middleware layers are appended to the middleware list in this exact order:
  1. ColabProxyMiddleware — must be first; intercepts every MCP message to set connection-state context values (fe_connected, proxy_token, proxy_port) and notify the client when connectivity changes.
  2. ToolInjectionMiddleware — injects the open_colab_browser_connection tool into every MCP tool list response, regardless of whether Colab is connected.
Because ColabProxyMiddleware runs first, the context values it sets are always available when ToolInjectionMiddleware and downstream tool handlers run.
4

Client calls open_colab_browser_connection

When the MCP client calls the injected tool, the server opens the following URL in the system’s default browser:
https://colab.research.google.com/notebooks/empty.ipynb#mcpProxyToken=<token>&mcpProxyPort=<port>
The mcpProxyToken and mcpProxyPort fragments are read by the Colab UI to know where and how to connect back.
5

Colab authenticates and opens a WebSocket connection

The Colab browser session reads the token and port from the URL fragment, then opens a WebSocket connection to ws://localhost:<port> — authenticating with the token in either an ?access_token=<token> query parameter or an Authorization: Bearer <token> header.
6

Tools become available

Once the WebSocket connection is established, ColabProxyMiddleware detects the state change from disconnected to connected and sends a notifications/tools/list_changed notification to the MCP client. The client then re-fetches the tool list and discovers the full set of notebook tools provided by the Colab session.
Only one browser tab can be connected to colab-mcp at a time. If a second connection is attempted while one is already active, the server immediately closes it with WebSocket close code 1013 (“Server is busy”). To switch sessions, close the existing browser tab first.

​
Further Reading

For deeper implementation details, see:
  • WebSocket Server — how ColabWebSocketServer handles authentication, single-client exclusivity, and message streaming.
  • Session Proxy — how ColabSessionProxy, ColabProxyClient, and the middleware layers wire everything together.

Build docs developers (and LLMs) love

Get started for freeTalk to us