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.

When something goes wrong with Colab MCP, the best first step is to check the log file. By default, Colab MCP writes logs to a temporary directory named colab-mcp-logs-* under your system’s temp folder (e.g. /tmp/colab-mcp-logs-<random>/colab-mcp.YYYY-MM-DD_HH-MM-SS.log). The log captures WebSocket events, connection state changes, and MCP message activity at INFO level. Use --log /path/to/dir when starting the server to write logs to a custom directory. Once you have the log open, look for lines indicating WebSocket connection attempts, authentication responses, or connection state transitions — these are usually where problems surface.
Cause: Colab MCP uses the notifications/tools/list_changed MCP notification to signal to the client that new notebook tools have become available after the browser connection is established. If your MCP client does not support this notification, the tool list will never be refreshed and the notebook tools will remain hidden.Fix: Use a client that supports notifications/tools/list_changed. Verified supported clients include:
  • Gemini CLI
  • Claude Code
  • Windsurf
Some clients may also require a manual tool refresh or a full restart to pick up the updated tool list after connecting. Consult your client’s documentation for details.Also check: Confirm that the colab-mcp process started successfully and that the proxy is running. The proxy is enabled by default and cannot be disabled via a command-line flag — if the server started without errors, the proxy should be active.
The open_colab_browser_connection tool waits up to 60 seconds for the Colab browser tab to establish a WebSocket connection back to the local server. If the tab does not connect within that window, the tool returns false and the connection attempt is considered failed.Common causes:
  • The browser tab did not open or failed to load (e.g. colab.research.google.com or colab.google.com is not reachable from your network).
  • A firewall or security policy is blocking the outbound WebSocket connection from the browser to localhost.
  • A token mismatch between the URL and the running server (e.g. the server was restarted after the URL was generated).
Fix:
  1. Confirm that colab.research.google.com and colab.google.com are reachable in your browser.
  2. Check that nothing is blocking WebSocket connections to localhost on the port shown in the logs.
  3. Call open_colab_browser_connection again to generate a fresh URL with the current token and retry the connection.
Check the log file for lines referencing WebSocket server on ws://localhost:<port> and any connection errors that follow.
These errors indicate a WebSocket authentication failure during the handshake between the Colab browser tab and the local server.401 Unauthorized: The Colab tab did not send an Authorization header and the token was not present in the URL’s access_token query parameter. This typically means the token was not passed correctly in the URL when the browser tab was opened.403 Forbidden: The token was present but did not match the token the server is currently holding. This most commonly happens when the Colab MCP server was restarted after the browser URL was generated — the server issues a new token on each start, invalidating any previously opened URLs.Fix: Call open_colab_browser_connection again. This generates a fresh URL containing the current server token and opens a new Colab tab with the correct credentials.
Colab MCP enforces single-client exclusivity — only one Colab browser tab can be connected to the local WebSocket server at a time. If a second tab attempts to connect while one is already active, the server closes the new connection with WebSocket close code 1013 and the reason "Server is busy".Fix: Close the existing connected Colab tab first, then open a new connection by calling open_colab_browser_connection again. Once the first tab disconnects, the server becomes available to accept a new connection.
Cause: If your environment has a non-standard default PyPI package index configured (a common situation for Googlers), uvx may fail to resolve or download the colab-mcp package from GitHub.Fix: Explicitly pass the public PyPI index URL to uvx by adding "--index" and "https://pypi.org/simple" to the args array in your MCP configuration:
{
  "mcpServers": {
    "colab-mcp": {
      "command": "uvx",
      "args": ["--index", "https://pypi.org/simple", "git+https://github.com/googlecolab/colab-mcp"],
      "timeout": 30000
    }
  }
}
This forces uvx to resolve dependencies against the standard public index regardless of any local index overrides.
By default, Colab MCP writes logs to a directory named colab-mcp-logs-* created under the system temp directory (e.g. /tmp on Linux/macOS). The exact path is printed to the MCP server output at startup.To use a custom log directory, pass the --log flag when starting the server:
colab-mcp --log /path/to/your/log/dir
Log files inside that directory are named using the pattern:
colab-mcp.YYYY-MM-DD_HH-MM-SS.log
Each log file captures events at INFO level and above, including:
  • WebSocket server startup and port binding
  • Incoming connection attempts, including origin and authentication results
  • Connection state changes (connected / disconnected)
  • MCP message activity between the server and the Colab browser tab
Opening the most recent log file and scanning for WARNING or ERROR lines is usually the fastest way to identify what went wrong.
If you encounter a problem that isn’t covered here, or you have a feature request, please open a thread on the GitHub Discussions page rather than filing an issue directly:https://github.com/googlecolab/colab-mcp/discussions

Build docs developers (and LLMs) love

Get started for freeTalk to us