Google Colab MCP Server
You can use any MCP-compatible AI agent to control Google Colab or Jupyter runtimes remotely for code execution, notebook/file management, environment setup, hardware monitoring, and ML job orchestration.
Run Python code and notebook cells in Colab/Jupyter sessions, with output capture (stdout, stderr, rich display).
Create, edit, delete, execute, and export .ipynb notebooks.
Manage runtime sessions: create, inspect, interrupt, restart, and list active sessions.
Upload, download, read, write, delete, move, and list files in the sandboxed workspace.
Install, uninstall, and query Python packages inside the runtime.
Inspect GPU, CPU, RAM, and disk resources of the runtime.
Launch background training/evaluation/model-saving/export jobs and track them via job IDs.
Retrieve job status, logs, progress, artifacts, and cancel jobs.
Optionally use Colab with verified provider detection, or local/remote Jupyter/Docker backends.
Allows AI agents to use Google Colab as an execution environment, including running code, managing notebooks, installing packages, inspecting GPU/CPU/RAM, running training jobs, and managing files and artifacts.
Allows controlling any Jupyter-compatible runtime as an execution environment, providing code execution, notebook management, package installation, hardware introspection, training jobs, and file/artifact management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Colab MCP Server Run this PyTorch training script in Colab on a GPU"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 / DockerThis 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 withhttp(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
retryableflag 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-mcpTry it with the included example client:
python examples/example_client.pyConnect 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 insteadDocumentation
Internal Audit — technical debt found before the v0.2 rework
Testing
pytest -q121 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 toolscolab_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
Scored across 40 tools
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.
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.
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.
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
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP runtime where your agent publishes its own tools by tool call and keeps working.
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
A full backend your AI coding agent can set up over MCP
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that bridges local AI agents to Google Colab notebooks, enabling execution of Python code and interaction with notebook states directly from the agent.1Apache 2.0
- AlicenseBqualityDmaintenanceLocal-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.599Apache 2.0
- AlicenseAqualityDmaintenanceEnables 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.103MIT
- AlicenseAqualityDmaintenanceMCP 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.39MIT