Automating Google Colab with AI Agents: A Guide to colab-mcp and FastMCP

How to Design a Production-Ready AI Agent That Automates Google Colab Workflows Using Colab-MCP, MCP Tools, FastMCP, and Kernel Execution

Google’s newly released colab-mcp is an open-source Model Context Protocol server that allows AI agents to programmatically control notebook runtimes. It enables tools like Claude Code and Gemini CLI to execute code, manage cells, and handle persistent kernel states via a structured JSON-RPC interface.

Why This Matters

Moving from manual notebook execution to agentic automation requires bridging the gap between LLM reasoning and live environments. While ideal models generate code snippets, production reality demands handling authenticated WebSocket bridges, managing GPU/TPU VM assignments, and implementing robust retry logic with exponential backoff to handle transient execution failures or resource exhaustion.

Key Insights

• The colab-mcp server supports two operational modes: Session Proxy for browser UI synchronization and Runtime Mode for direct Jupyter kernel execution.
• FastMCP framework automates JSON Schema generation from Python type hints, enabling seamless tool registration for AI agents.
• Persistent state management allows agents to maintain variables and data structures across multiple cell executions within the same kernel session.
• Security is maintained through authenticated WebSocket bridges using tokens and OAuth2-based VM assignment for Colab runtimes.
• The architecture supports dependency-aware cell sequencing to prevent downstream failures when a prerequisite cell execution fails.

Working Examples

A FastMCP tool implementation for direct Python code execution in a Colab runtime.

from fastmcp import FastMCP
mcp = FastMCP("colab-mcp-tutorial")
@mcp.tool()
def runtime_execute_code(code: str) -> dict:
    """Execute Python code directly in a Colab kernel (Runtime Mode)."""
    import io, contextlib, traceback
    stdout_buf = io.StringIO()
    try:
        with contextlib.redirect_stdout(stdout_buf):
            exec(code, {"__builtins__": __builtins__})
        return {"outputs": [{"output_type": "stream", "name": "stdout", "text": stdout_buf.getvalue()}]}
    except Exception:
        return {"outputs": [{"output_type": "error", "traceback": traceback.format_exc()}]}

Practical Applications

• Use Case: Claude Code or Gemini CLI utilizing colab-mcp to build data analysis notebooks step-by-step. Pitfall: Failing to implement timeout handling, leading to agent hangs during long-running GPU tasks.
• Use Case: Automated statistical reporting where an agent generates data, computes variance, and adds markdown summaries. Pitfall: Ignoring dependency-aware cell sequencing, which causes downstream errors if a prerequisite import fails.

References:

• https://www.marktechpost.com/2026/03/23/how-to-design-a-production-ready-ai-agent-that-automates-google-colab-workflows-using-colab-mcp-mcp-tools-fastmcp-and-kernel-execution/