Skip to main content
Glama
Sign In
colab-mcp

colab-mcp

by DaneshSelwal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: JupyterMCP

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.

Available Tools

13 tools
connect_colabD

Inputs: notebook_url. Returns: backend, message, connected, proxy_port, +6 more

execute_ml_pipelineD

Inputs: code_block (required). Returns: status, stderr, stdout, traceback, +4 more

fetch_remote_datasetD

Inputs: extract_to (required), download_url (required). Returns: status, stderr, stdout, cell_id, +7 more

get_colab_outputD

Inputs: cell_id. Returns: status, stderr, stdout, cell_id, +7 more

list_colab_cellsD

Inputs: no named parameters. Returns: result

open_colab_browser_connectionA

Checks whether a Google Colab proxy session is already connected. Returns a boolean representing whether the headless proxy connection is available.

Inputs: no named parameters. Returns: result

read_colab_cellD

Inputs: cell_id (required). Returns: code, cell_id, outputs, preview, +2 more

run_colab_cellD

Inputs: wait, cell_id, timeout_seconds. Returns: status, stderr, stdout, cell_id, +7 more

run_colab_codeD

Inputs: code (required), mode, wait, timeout_seconds. Returns: status, stderr, stdout, cell_id, +7 more

run_runtime_codeD

Inputs: code (required). Returns: status, stderr, stdout, cell_id, +7 more

save_colab_notebookD

Inputs: no named parameters. Returns: message, success, notebook_url

setup_ml_workspaceD

Inputs: packages (required). Returns: status, stderr, stdout, cell_id, +7 more

write_colab_cellD

Inputs: code (required), mode, cell_id. Returns: code, cell_id, outputs, preview, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    D1.7/5.0

    Scored across 13 tools

    Disambiguation2/5

    Several tools appear to serve similar purposes: run_colab_cell, run_colab_code, run_runtime_code, and execute_ml_pipeline all seem to execute code, while connect_colab and open_colab_browser_connection overlap in establishing/checking a connection. Without descriptions, it's hard for an agent to pick the right tool.

    Naming Consistency3/5

    Most tools follow a verb_noun snake_case pattern, but there's inconsistency: some include 'colab' (e.g., list_colab_cells) while others do not (e.g., setup_ml_workspace, fetch_remote_dataset). Also, the verbs vary widely, making the naming feel less systematic than a strict verb_noun convention.

    Tool Count4/5

    13 tools is within a reasonable range for a Colab-focused server. However, the presence of four overlapping execution tools inflates the count and suggests some consolidation could improve the set without losing functionality.

    Completeness3/5

    The tool surface covers core cell operations (read, write, run, output) and notebook saving, but lacks obvious lifecycle operations like deleting a cell or creating a notebook. The ML-related tools (setup workspace, fetch dataset, pipeline) add breadth but also introduce unclear boundaries and gaps, such as no explicit tool for managing datasets beyond fetching.

    Resources

    Related MCP Connectors

    Related MCP Servers