Skip to main content
Glama
Google Colab MCP Server

Google Colab MCP Server

by MOT1209

Google Colab MCP Server

A standalone, framework-agnostic, production-grade Model Context Protocol server that lets any MCP-compatible AI agent or application control Google Colab — or any Jupyter-compatible runtime — as an execution environment: run code, manage notebooks, install packages, inspect GPU/CPU/RAM/disk, run training jobs, manage datasets and environment profiles, and track artifacts.

Any AI Agent (KingAgent, Claude, Cursor, VS Code, a custom agent, ...)
      │
      │  MCP (stdio / SSE)
      ▼
Google Colab MCP Server   ←—— this repository
      │
      ▼
Runtime Manager  →  Runtime Provider  →  Execution Backend
      │
      ▼
Google Colab (verified) / local Jupyter / remote Jupyter / Docker

This server has no dependency on any specific agent or framework — not KingAgent, not Claude, not LangChain, CrewAI, AutoGen, or OpenAI Agents. You can plug it into any of them without modifying this codebase.

Google Colab is a first-class, verified provider

Colab has no public API for arbitrary remote execution; the only documented path in is the Jupyter kernel protocol. Because a generic Jupyter kernel and a real Colab kernel speak that same protocol, this server actively verifies — after connecting — that a session created with provider: "colab" is genuinely running on Colab (checking for google.colab/Colab environment markers) and refuses the connection otherwise, rather than silently treating any Jupyter kernel as "Colab" the way most projects in this space do. See docs/COLAB.md.

Related MCP server: colab-mcp

Features

  • 59 MCP tools across runtime/session management, code execution, notebooks, files, packages/environments, GPU/hardware introspection, ML training, datasets, and jobs/artifacts.

  • 7 MCP resources: colab://runtime, colab://sessions, colab://jobs, colab://notebooks, colab://artifacts, colab://environments, colab://datasets.

  • RuntimeProvider abstraction — colab, local_jupyter, remote_jupyter, docker — with a documented, honest lifecycle (discovering → connecting → authenticating → initializing → ready → running/idle → disconnected/failed/reconnecting) and a background health monitor with bounded auto-reconnect.

  • Async job engine (queued/starting/running/paused/completed/ failed/cancelled/timeout) with structured metrics, and each job tracks the session/runtime it ran on.

  • Environment & dataset management: package install/list/export, reusable EnvironmentProfiles, and a checksummed, versioned dataset store with http(s):// caching.

  • Multi-method GPU detection (nvidia-smi, pynvml, torch, TensorFlow) — not dependent on any one ML framework being installed.

  • Security layer: auth, per-tool and per-session allow/deny lists, a dangerous-tool confirmation policy, path sandboxing (locally and inside the runtime), output/file size limits, rate limiting, timeouts, secret redaction, and audit logging.

  • Structured errors with a retryable flag and provider/network/ auth-specific categories — never a raw crash.

  • No framework lock-in on the Colab side either: whatever ML framework your code imports (PyTorch, TensorFlow, Transformers, scikit-learn, XGBoost, ...) runs inside the target runtime — this server doesn't impose one.

Quick start

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Local kernel for dev/testing (no real Colab connection needed):
pip install ipykernel
python3 -m ipykernel install --user --name python3

cp .env.example .env
google-colab-mcp

Try it with the included example client:

python examples/example_client.py

Connect a real MCP client (any of them) by pointing it at the google-colab-mcp command — see config/mcp_client_example.json, docs/SETUP.md, and docs/COLAB.md for how to attach to a real, verified Colab runtime.

Example: an agent using this server

Agent: "Run this code in Colab and use a GPU if one is available."
  → colab_create_session (provider: "colab")
  → colab_get_runtime / colab_get_gpu   # is a GPU present?
  → colab_execute_code                  # run the code (device chosen accordingly)
  → colab_run_training / colab_get_job  # if it was a long training run instead

Documentation

Testing

pytest -q

121 tests (unit + real end-to-end execution against a locally-launched Jupyter kernel, skipped automatically if none is available), including a dedicated test proving a plain Jupyter kernel is correctly rejected when requested as provider: "colab".

License

MIT — see LICENSE.

Available Tools

40 tools
colab_add_cellB

Add a single cell to a notebook, at an index or appended to the end.

Inputs: path (required), source (required), index, cell_type.

colab_cancel_jobB

Request cancellation of a running or queued job.

Inputs: job_id (required).

colab_create_directoryA

Create a directory (and parents) in the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), session_id.

colab_create_notebookA

Create a new, empty .ipynb notebook inside the sandboxed workspace.

Inputs: path (required), kernel_name.

colab_create_sessionB

Open a new runtime session (a Colab/Jupyter kernel connection). Omit connection_file to launch a local kernel.

Inputs: label, connection_file.

colab_delete_cellC

Delete one cell by index.

Inputs: path (required), index (required).

colab_delete_fileA

Delete a file or directory (recursively) in the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), session_id.

colab_download_fileA

Download a file from the runtime's sandboxed workspace as base64. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), session_id.

colab_edit_cellA

Replace the source of one existing cell by index.

Inputs: path (required), index (required), source (required).

colab_evaluate_modelB

Run evaluation code synchronously against a runtime session and return its output.

Inputs: code (required), session_id, timeout_seconds.

colab_execute_cellC

Execute a single notebook cell by index against a runtime session.

Inputs: path (required), index (required), session_id, timeout_seconds.

colab_execute_codeB

Execute a snippet of Python code in a Colab/Jupyter runtime session and return stdout, stderr, the last expression's repr, and any rich display data.

Inputs: code (required), session_id, timeout_seconds.

colab_execute_notebookB

Execute every code cell in a notebook, in order, against a runtime session.

Inputs: path (required), session_id, timeout_seconds.

colab_export_modelB

Run model-export code (e.g. ONNX/TorchScript) in a runtime session and register the exported artifact.

Inputs: code (required), name, job_id, session_id, +2 more.

colab_export_notebookB

Export a notebook as raw .ipynb JSON or as a flattened Python script.

Inputs: path (required), format.

colab_get_artifactsB

List artifacts (models, datasets, logs, metrics, reports) produced by a job, or all jobs if job_id is omitted.

Inputs: job_id.

colab_get_cpuB

Get CPU core count and utilization for a runtime session.

Inputs: session_id.

colab_get_diskB

Get disk usage for a runtime session.

Inputs: session_id.

colab_get_gpuA

Get GPU/VRAM info for a runtime session (device name, memory, count).

Inputs: session_id.

colab_get_jobB

Get the status, progress, and result of a job (e.g. a training run) by job_id.

Inputs: job_id (required), include_logs.

colab_get_logsA

Get a job's accumulated log lines, optionally only the last N.

Inputs: job_id (required), tail.

colab_get_memoryA

Get RAM total/available/used for a runtime session.

Inputs: session_id.

colab_get_notebookA

Read a notebook's cells and metadata.

Inputs: path (required).

colab_get_package_versionC

Get the installed version of a specific package in the runtime.

Inputs: package (required), session_id.

colab_get_runtimeB

Get overall runtime status: active sessions, Python version, CUDA/torch availability.

Inputs: session_id.

colab_install_packageA

Install a Python package (e.g. 'transformers', 'torch==2.3.0') inside the runtime via pip.

Inputs: package (required), session_id.

colab_list_filesA

List files and directories under a path in the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path, session_id.

colab_list_jobsA

List all known jobs, optionally filtered by status (queued/starting/running/completed/failed/cancelled/timeout).

Inputs: status.

colab_list_packagesB

List all installed packages and their versions in the runtime.

Inputs: session_id.

colab_move_fileB

Move/rename a file within the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: source (required), destination (required), session_id.

colab_read_fileA

Read a text file's contents from the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), session_id.

colab_restart_runtimeA

Restart a runtime session's kernel (clears all variables/state).

Inputs: session_id.

colab_run_trainingA

Start a training run as a background job: submits Python training code (any framework) to a runtime session and returns a job_id immediately. Poll with colab_get_job / colab_get_logs.

Inputs: code (required), session_id, timeout_seconds.

colab_save_modelB

Run model-saving code in a runtime session, then (optionally) register the resulting file under a job's artifacts via colab_get_artifacts.

Inputs: code (required), name, job_id, session_id, +2 more.

colab_stop_executionB

Interrupt whatever is currently executing in a runtime session (like a keyboard interrupt).

Inputs: session_id.

colab_stop_trainingB

Interrupt a running training job and mark it cancelled.

Inputs: job_id (required).

colab_uninstall_packageA

Uninstall a Python package from the runtime via pip.

Inputs: package (required), session_id.

colab_update_notebookA

Replace a notebook's entire cell list.

Inputs: path (required), cells (required).

colab_upload_fileB

Upload base64-encoded file content into the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), content_base64 (required), session_id.

colab_write_fileB

Write text content to a file in the runtime's sandboxed workspace. Path is relative to the runtime's sandboxed workspace (e.g. /content/mcp_workspace).

Inputs: path (required), content (required), session_id.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 40 tools

    Disambiguation4/5

    Most tools follow a clear resource-action split (notebook, file, package, runtime, job), so an agent can usually pick the right one. However, cancel_job, stop_training, and stop_execution overlap in purpose, and save_model/export_model are difficult to distinguish without reading deeply.

    Naming Consistency5/5

    All tools use the colab_ prefix with verb_noun snake_case, making the API highly predictable. Even large groups like colab_get_gpu/cpu/memory/disk follow a uniform pattern.

    Tool Count2/5

    Forty tools is a large surface for a single MCP server, falling into the 'too heavy' range. Even though each tool is individually meaningful, the set bundles notebook, file, package, runtime, and job-management responsibilities that could be separate servers.

    Completeness4/5

    The toolset covers notebook CRUD/cell editing/execution, file management, package management, runtime introspection, and training-job lifecycle. Minor gaps exist—no dedicated notebook delete/list or cell retrieval-by-index—but file tools and execute options provide workarounds.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Local-first MCP server for controlling Google Colab as a development, shell, file, and training runtime, with tools for notebook editing, GPU acceleration, and file transfer.
      59
      9
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible AI assistants to run Python code on Google Colab GPU/TPU runtimes, supporting accelerators like T4, A100, H100, with background execution and Google Drive integration.
      10
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that allocates Google Colab GPU runtimes (T4/L4) and executes Python code on them. Lets any MCP-compatible AI assistant run GPU-accelerated code without local GPU hardware.
      3
      9
      MIT