🪐 Colab MCP (Model Context Protocol)

An MCP (Model Context Protocol) server that seamlessly bridges your local AI agent to a Google Colab session running in your browser.

✨ Features

• Connects local AI assistants directly to browser-based Colab notebooks
• Supports executing Python code in Colab via the agent
• Reads and interacts with Colab notebook states

💻 Supported Clients

This MCP server requires a client that supports notifications/tools/list_changed and must be running locally on your device.

Popular clients that meet these criteria include:

• Gemini CLI
• Claude Code
• Windsurf

🚀 Installation & Setup

1. Install uv (an extremely fast Python package installer and resolver):

   pip install uv
   

2. Configure your MCP Client (e.g., in your mcp.json or equivalent configuration file):

   {
     "mcpServers": {
       "colab-mcp": {
         "command": "uvx",
         "args": ["git+https://github.com/googlecolab/colab-mcp"],
         "timeout": 30000
       }
     }
   }
   

   Note for Googlers (or those with non-standard package indexes): You may need to add --index https://pypi.org/simple to the args array.

💬 Issues & Discussions

We use GitHub Discussions as our primary venue for issue discussion and feature requests.

As discussions mature into clear action items, the maintainers will convert them into tracked issues. This workflow helps us ensure that the issue tracker remains deduplicated, well-understood, and highly actionable.

⚠️ Please do <u>NOT</u> open issues directly.

🤝 Contributing

While we appreciate community interest, we currently do not have the bandwidth to review external contributions. We want to avoid user Pull Requests languishing without review, so we are not accepting external contributions at this time.

If you have a great idea or encounter a pain point, we would love to hear about it on our Discussions page!

---

🛠️ Internal (For Colab Developers)

Prerequisites

• uv is required (pip install uv)

• Configure git hooks to run repository presubmits:

  git config core.hooksPath .githooks
  

Local Development Setup (Gemini CLI)

To test your local checkout with the Gemini CLI, use this configuration:

{
  "mcpServers": {
    "colab-mcp": {
      "command": "uv",
      "args": ["run", "colab-mcp"],
      "cwd": "/path/to/github/colab-mcp",
      "timeout": 30000
    }
  }
}

MCP_Colab