# 🪐 Colab MCP (Model Context Protocol)

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Supported-brightgreen.svg)](https://modelcontextprotocol.io)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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](https://github.com/google/gemini-cli)
- [Claude Code](https://github.com/anthropics/claude-code)
- [Windsurf](https://codeium.com/windsurf)

## 🚀 Installation & Setup

1. **Install `uv`** (an extremely fast Python package installer and resolver):
   ```bash
   pip install uv
   ```

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

   ```json
   {
     "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](https://github.com/googlecolab/colab-mcp/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](https://github.com/googlecolab/colab-mcp/discussions) page!

---

## 🛠️ Internal (For Colab Developers)

### Prerequisites

- `uv` is required (`pip install uv`)
- Configure git hooks to run repository presubmits:

  ```bash
  git config core.hooksPath .githooks
  ```

### Local Development Setup (Gemini CLI)

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

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