Headless Colab MCP Server

colab-mcp is a FastMCP server for controlling Google Colab notebooks through a secure, headless WebSocket architecture. Agents can create, edit, run, and inspect notebook cells without browser automation or UI scraping.

---

Features

• Headless Operation — Run notebook operations through a secure WebSocket proxy
• Zero Browser Management — No Chromium, browser profiles, or DOM scraping
• ML-Ready Tooling — Workspace setup, dataset handling, and pipeline execution
• Structured Results — Typed stdout, stderr, file paths, and error details
• FastMCP Integration — Clean MCP server interface for tool composition

---

Architecture

The server uses two cooperating layers:

ColabSessionProxy

• Starts a localhost WebSocket server
• Generates a one-time connection URL with mcpProxyToken and mcpProxyPort
• Waits for an authenticated Colab tab to attach

NotebookController

• Exposes the stable MCP tool surface
• Discovers proxy capabilities from the connected Colab frontend
• Maps server-owned tools to proxy-backed cell operations
• Falls back to direct runtime execution only when needed

---

Requirements

Requirement	Version
Python	3.13+
uv	Latest
Google Colab	Active browser session

---

Installation

uv sync
uv run colab-mcp

---

Configuration

Add this to your MCP configuration:

{
  "mcpServers": {
    "colab-mcp-local": {
      "command": "uv",
      "args": ["run", "colab-mcp"],
      "cwd": "${workspaceFolder}",
      "timeout": 30000
    }
  }
}

---

API Reference

Core Notebook Tools

Tool	Description
connect_colab(notebook_url?)	Initialize connection and retrieve proxy URL
list_colab_cells()	List all cells in the notebook
read_colab_cell(cell_id)	Read a specific cell
write_colab_cell(code, cell_id?, mode?)	Write code to a cell
run_colab_cell(cell_id?, wait?, timeout_seconds?)	Execute a cell
run_colab_code(code, mode?, wait?, timeout_seconds?)	Write and execute code in one step
get_colab_output(cell_id?)	Retrieve execution output
save_colab_notebook()	Save the notebook
run_runtime_code(code)	Execute code directly in the runtime

ML Workflow Tools

Tool	Description
setup_ml_workspace(packages)	Install packages and create standard data directories
fetch_remote_dataset(download_url, extract_to)	Download and extract datasets
execute_ml_pipeline(code_block)	Execute Python blocks with structured results

---

Usage

1. Start the MCP server.
2. Call connect_colab to get a connect_url, proxy_token, and proxy_port.
3. Paste the connect_url into an active Colab tab.
4. Wait for the proxy connection to establish.
5. Run notebook operations through the MCP tools.

Example

uv run colab-mcp
connect_colab()
setup_ml_workspace(["pandas", "scikit-learn"])
fetch_remote_dataset(url, "/content/data")
execute_ml_pipeline(training_code)
get_colab_output()

---

Development & Verification

PYTHONPATH=src python scripts/smoke_test.py
PYTHONPATH=src py -m pytest
cat RELEASE_CHECKLIST.md

Test coverage

• Proxy capability discovery
• Native Colab argument mapping
• Cell ID extraction
• ML tool routing through proxy
• Execution result normalization

---

License

This project is licensed under the Apache License 2.0.

---

Acknowledgments

This headless WebSocket proxy architecture was inspired by the open-source work provided by the Google Colab team.