# Google Colab MCP Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
A **Model Context Protocol (MCP)** server that enables AI assistants to interact directly with Google Colab notebooks. This server provides seamless integration between AI assistants (Claude, ChatGPT, etc.) and Google Colab environments for automated notebook creation, code execution, and data science workflows.
**Key Updates**: Enhanced timeout handling, robust error management, and non-blocking code execution. The system provides comprehensive error reporting and stable performance during long-running operations.
## Features
**Core Capabilities**
- **Automatic OAuth2 Authentication** - One-time setup with secure Google authentication
- **Persistent Chrome Profile Management** - Maintains login sessions across restarts
- **Complete Notebook Operations** - Create, read, update, list, and manage Colab notebooks
- **Code Execution Engine** - Execute Python code directly in Colab environments with real-time feedback
- **Package Management** - Install and manage Python packages in Colab runtime environments
- **File Operations** - Upload and manage files within Colab environments
- **Session Management** - Handle Colab runtime sessions with automatic cleanup
- **Enhanced Error Handling** - Comprehensive error reporting with detailed troubleshooting
- **Smart Timeout Management** - Non-blocking execution with configurable timeout handling
- **Profile Optimization** - Tools to manage Chrome profiles and session data efficiently
- **Execution Monitoring** - Real-time tracking of code execution status and performance
- **Background Processing** - Support for long-running operations without blocking the main process
## Use Cases
- **AI-Powered Data Science**: Enable AI assistants to create and execute data analysis notebooks
- **Automated ML Workflows**: Build machine learning pipelines through natural language interactions
- **Educational Tools**: Create interactive coding tutorials and examples with AI assistance
- **Research Automation**: Automate repetitive research tasks and data processing in Colab
- **Code Generation**: Generate, test, and validate code snippets in a cloud environment
- **Collaborative Development**: Share and manage notebooks through AI-driven conversations
## Getting Started
### Installation
**Install from PyPI (Recommended):**
```bash
pip install google-colab-mcp
```
**Install from Source:**
```bash
git clone https://github.com/inkbytefo/google-colab-mcp.git
cd google-colab-mcp
pip install -e .
```
### Configuration Setup
**Automated Initialization (Recommended):**
Use the AI assistant for setup:
```
"Initialize my Google Colab MCP configuration"
```
**Manual Initialization:**
```bash
python -m mcp_colab_server.config_manager --init
```
This command creates your configuration directory at `~/.mcp-colab/` containing:
- Server configuration files
- Logs directory for troubleshooting
- Credentials template for Google API setup
### Google Cloud Setup
**Required Steps:**
1. Visit [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing project
3. Enable the **Google Drive API** for your project
4. Create **OAuth 2.0 credentials** (select "Desktop Application" type)
5. Download the credentials file as `credentials.json`
6. Place `credentials.json` in your `~/.mcp-colab/` directory
**Important Notes:**
- Ensure you select "Desktop Application" when creating OAuth 2.0 credentials
- The credentials file must be named exactly `credentials.json`
- Keep your credentials file secure and never commit it to version control
### Authentication Setup
**Run the setup script:**
```bash
python -m mcp_colab_server.setup
```
**The setup process will:**
- Validate your credentials file format and content
- Launch a browser window for Google OAuth authentication
- Save authentication tokens to `~/.mcp-colab/token.json`
- Perform a connection test to verify everything works
**Check configuration status:**
```bash
python -m mcp_colab_server.config_manager --status
```
This command displays your current configuration status, authentication state, and any potential issues.
### Chrome Profile Management
The system automatically manages Chrome browser profiles to maintain persistent Google login sessions:
**Profile Management Commands:**
```bash
# View all Chrome profiles and their status
python -m mcp_colab_server.config_manager --profile-summary
# Optimize profiles by cleaning cache and temporary files
python -m mcp_colab_server.config_manager --optimize-profiles
# Remove old or unused profiles
python -m mcp_colab_server.config_manager --clean-profiles
```
**Profile Management Benefits:**
- **Persistent Authentication**: Google login sessions are remembered between server restarts
- **Faster Startup Times**: No need to re-authenticate for each session
- **Automatic Cleanup**: Profiles are automatically optimized to minimize disk usage
- **User Isolation**: Each user maintains their own separate profile directory
- **Session Recovery**: Ability to recover from browser crashes or unexpected shutdowns
### MCP Integration
**For Claude Desktop Application:**
Add the following configuration to your Claude desktop settings:
```json
{
"mcpServers": {
"google-colab-mcp": {
"command": "google-colab-mcp",
"args": [],
"env": {
"MCP_COLAB_LOG_LEVEL": "INFO"
}
}
}
}
```
**For Development or Custom Setup:**
```json
{
"mcpServers": {
"google-colab-mcp": {
"command": "python",
"args": ["-m", "mcp_colab_server.server"],
"cwd": "/path/to/your/google-colab-mcp",
"env": {
"MCP_COLAB_LOG_LEVEL": "INFO"
}
}
}
}
```
## Available Tools
| Tool Name | Function | Example Usage |
|-----------|----------|---------------|
| `init_user_config` | Initialize user configuration directory | "Initialize my Google Colab MCP configuration" |
| `check_auth_status` | Verify authentication and connection status | "Check my Google authentication status" |
| `setup_google_credentials` | Get step-by-step setup instructions | "How do I set up Google credentials?" |
| `authenticate_google` | Complete Google OAuth authentication flow | "Authenticate with Google" |
| `create_colab_notebook` | Create a new Colab notebook | "Create a notebook called 'Data Analysis'" |
| `list_notebooks` | List all accessible Colab notebooks | "Show me my Colab notebooks" |
| `get_notebook_content` | Retrieve notebook content and structure | "Show me the content of my latest notebook" |
| `run_code_cell` | Execute Python code in Colab runtime | "Run this code: import pandas as pd" |
| `install_package` | Install Python packages in Colab | "Install matplotlib in my notebook" |
| `upload_file_to_colab` | Upload files to Colab environment | "Upload data.csv to my notebook" |
| `get_runtime_info` | Get Colab runtime status and information | "What's the status of my Colab runtime?" |
| `get_session_info` | Get current session details | "Show me my current Colab session" |
| `get_chrome_profile_info` | Get Chrome profile status and metrics | "Check my browser profile status" |
| `clear_chrome_profile` | Reset Chrome profile and clear data | "Clear my browser data and reset login" |
## Example Conversations
**Working with AI Assistants (Claude/ChatGPT):**
**Notebook Creation:**
```
User: "Create a new Colab notebook for analyzing sales data"
AI: Creates notebook and responds with notebook URL and ID
```
**Package Installation and Code Execution:**
```
User: "Install pandas and matplotlib, then create a simple plot"
AI: Installs packages and generates plotting code in your Colab
```
**Notebook Management:**
```
User: "List all my notebooks and show me the most recent one"
AI: Lists notebooks and displays the content of the latest one
```
**Complex Data Analysis:**
```
User: "Load my sales data, calculate monthly trends, and create a visualization"
AI: Executes multi-step data analysis workflow in Colab
```
## System Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AI Assistant │◄──►│ MCP Server │◄──►│ Google Colab │
│ (Claude, etc.) │ │ (This Project) │ │ Notebooks │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Google Drive │
│ API │
└──────────────────┘
```
**Component Overview:**
The server functions as a bridge between AI assistants and Google Colab, utilizing:
- **Google Drive API** for notebook management and storage operations
- **Selenium WebDriver** for browser automation and code execution
- **MCP Protocol** for standardized communication with AI assistants
- **Chrome Profile Management** for persistent authentication sessions
**Data Flow:**
1. AI Assistant sends requests through MCP protocol
2. Server processes requests and manages authentication
3. Server interacts with Google Colab via Selenium automation
4. Results are returned to AI Assistant through MCP protocol
## Configuration
### Server Configuration
The server uses a configuration file located at `~/.mcp-colab/server_config.json`:
```json
{
"selenium": {
"browser": "chrome",
"headless": false,
"timeout": 30,
"profile": {
"use_persistent_profile": true,
"profile_directory": null,
"auto_create_profile": true
}
},
"colab": {
"execution_timeout": 300,
"max_retries": 3
},
"logging": {
"level": "INFO"
}
}
```
### Chrome Profile Configuration
The server supports persistent Chrome profiles to maintain Google login sessions:
**Key Features:**
- **Automatic Login**: No need to sign in repeatedly
- **Session Persistence**: Login data saved securely between sessions
- **Profile Management**: Built-in tools to manage and clear profile data
**Configuration Options:**
- `use_persistent_profile`: Enable/disable persistent profiles (default: true)
- `profile_directory`: Custom profile location (default: `~/.mcp-colab/chrome_profiles/default`)
- `auto_create_profile`: Automatically create profile directory (default: true)
**Management Commands:**
- `get_chrome_profile_info`: Check profile status and disk usage
- `clear_chrome_profile`: Clear profile data (requires re-authentication)
### MCP Configuration Options
**Advanced Configuration Example:**
```json
{
"mcpServers": {
"google-colab-mcp": {
"command": "google-colab-mcp",
"args": [],
"env": {
"MCP_COLAB_LOG_LEVEL": "INFO",
"MCP_COLAB_HEADLESS": "false"
},
"autoApprove": [
"list_notebooks",
"get_notebook_content",
"get_runtime_info"
]
}
}
}
```
**Environment Variables:**
- `MCP_COLAB_LOG_LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR)
- `MCP_COLAB_HEADLESS`: Run Chrome in headless mode (true/false)
- `MCP_COLAB_TIMEOUT`: Default timeout for operations (seconds)
## Troubleshooting
### Common Issues and Solutions
**Authentication Problems**
```bash
# Re-run the setup script to fix authentication issues
python -m mcp_colab_server.setup
# Clear existing tokens and re-authenticate
rm ~/.mcp-colab/token.json
python -m mcp_colab_server.setup
# Check current authentication status
python -m mcp_colab_server.config_manager --status
```
**Browser and WebDriver Issues**
```bash
# Update Chrome/Firefox to the latest version
# Install or update WebDriver dependencies
pip install webdriver-manager --upgrade
pip install selenium --upgrade
# Clear Chrome profiles if having persistent issues
python -m mcp_colab_server.config_manager --clean-profiles
```
**MCP Server Connection Problems**
```bash
# Test if the server starts correctly
google-colab-mcp
# Verify installation
pip show google-colab-mcp
# Reinstall if necessary
pip install --force-reinstall google-colab-mcp
```
### Debug Mode Configuration
Enable detailed logging for troubleshooting:
```json
{
"env": {
"MCP_COLAB_LOG_LEVEL": "DEBUG",
"MCP_COLAB_HEADLESS": "false"
}
}
```
### Performance Optimization
**For Better Performance:**
- Use headless mode (`MCP_COLAB_HEADLESS": "true"`) in production
- Regularly optimize Chrome profiles using `--optimize-profiles`
- Increase timeout values for slower network connections
- Monitor log files for performance bottlenecks
## Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information.
**Development Workflow:**
1. Fork the repository on GitHub
2. Create a feature branch: `git checkout -b feature/your-feature-name`
3. Make your changes and add tests
4. Commit your changes: `git commit -m 'Add amazing feature'`
5. Push to the branch: `git push origin feature/your-feature-name`
6. Open a Pull Request with a detailed description
**Development Setup:**
```bash
# Clone the repository
git clone https://github.com/inkbytefo/google-colab-mcp.git
cd google-colab-mcp
# Install in development mode
pip install -e ".[dev]"
# Run tests
python -m pytest tests/
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for complete details.
## Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) for providing the communication standard
- [Google Colab](https://colab.research.google.com/) for the cloud-based notebook platform
- [Anthropic](https://www.anthropic.com/) for Claude and MCP development
- The open-source community for valuable contributions and feedback
## Support and Resources
**Documentation and Help:**
- [Project Documentation](docs/)
- [Issue Tracker](https://github.com/inkbytefo/google-colab-mcp/issues)
- [Community Discussions](https://github.com/inkbytefo/google-colab-mcp/discussions)
- [Changelog and Updates](CHANGELOG.md)
**Getting Help:**
- Search existing issues before creating new ones
- Provide detailed information when reporting bugs
- Include log files and configuration details for faster resolution
---
**Project Information:**
- **Author:** inkbytefo
- **Version:** 1.0.1
- **Repository:** [github.com/inkbytefo/google-colab-mcp](https://github.com/inkbytefo/google-colab-mcp)
- **License:** MIT
- **Python Version:** 3.8+
*Built for the AI and Data Science community*
Raw data
{
"_id": null,
"home_page": null,
"name": "google-colab-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, google-colab, ai, assistant, jupyter, notebook, automation",
"author": "inkbytefo",
"author_email": "inkbytefo <inkbytefo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/af/1e/f6900c89e321d230cd01fa30fc4c13f72d85ebcd6f160e8f54fd7fd7937e/google_colab_mcp-1.0.1.tar.gz",
"platform": null,
"description": "# Google Colab MCP Server\r\n\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://modelcontextprotocol.io/)\r\n\r\nA **Model Context Protocol (MCP)** server that enables AI assistants to interact directly with Google Colab notebooks. This server provides seamless integration between AI assistants (Claude, ChatGPT, etc.) and Google Colab environments for automated notebook creation, code execution, and data science workflows.\r\n\r\n**Key Updates**: Enhanced timeout handling, robust error management, and non-blocking code execution. The system provides comprehensive error reporting and stable performance during long-running operations.\r\n\r\n## Features\r\n\r\n**Core Capabilities**\r\n- **Automatic OAuth2 Authentication** - One-time setup with secure Google authentication\r\n- **Persistent Chrome Profile Management** - Maintains login sessions across restarts\r\n- **Complete Notebook Operations** - Create, read, update, list, and manage Colab notebooks\r\n- **Code Execution Engine** - Execute Python code directly in Colab environments with real-time feedback\r\n- **Package Management** - Install and manage Python packages in Colab runtime environments\r\n- **File Operations** - Upload and manage files within Colab environments\r\n- **Session Management** - Handle Colab runtime sessions with automatic cleanup\r\n- **Enhanced Error Handling** - Comprehensive error reporting with detailed troubleshooting\r\n- **Smart Timeout Management** - Non-blocking execution with configurable timeout handling\r\n- **Profile Optimization** - Tools to manage Chrome profiles and session data efficiently\r\n- **Execution Monitoring** - Real-time tracking of code execution status and performance\r\n- **Background Processing** - Support for long-running operations without blocking the main process\r\n\r\n## Use Cases\r\n\r\n- **AI-Powered Data Science**: Enable AI assistants to create and execute data analysis notebooks\r\n- **Automated ML Workflows**: Build machine learning pipelines through natural language interactions\r\n- **Educational Tools**: Create interactive coding tutorials and examples with AI assistance\r\n- **Research Automation**: Automate repetitive research tasks and data processing in Colab\r\n- **Code Generation**: Generate, test, and validate code snippets in a cloud environment\r\n- **Collaborative Development**: Share and manage notebooks through AI-driven conversations\r\n\r\n## Getting Started\r\n\r\n### Installation\r\n\r\n**Install from PyPI (Recommended):**\r\n```bash\r\npip install google-colab-mcp\r\n```\r\n\r\n**Install from Source:**\r\n```bash\r\ngit clone https://github.com/inkbytefo/google-colab-mcp.git\r\ncd google-colab-mcp\r\npip install -e .\r\n```\r\n\r\n### Configuration Setup\r\n\r\n**Automated Initialization (Recommended):**\r\n\r\nUse the AI assistant for setup:\r\n```\r\n\"Initialize my Google Colab MCP configuration\"\r\n```\r\n\r\n**Manual Initialization:**\r\n```bash\r\npython -m mcp_colab_server.config_manager --init\r\n```\r\n\r\nThis command creates your configuration directory at `~/.mcp-colab/` containing:\r\n- Server configuration files\r\n- Logs directory for troubleshooting\r\n- Credentials template for Google API setup\r\n\r\n### Google Cloud Setup\r\n\r\n**Required Steps:**\r\n1. Visit [Google Cloud Console](https://console.cloud.google.com/)\r\n2. Create a new project or select an existing project\r\n3. Enable the **Google Drive API** for your project\r\n4. Create **OAuth 2.0 credentials** (select \"Desktop Application\" type)\r\n5. Download the credentials file as `credentials.json`\r\n6. Place `credentials.json` in your `~/.mcp-colab/` directory\r\n\r\n**Important Notes:**\r\n- Ensure you select \"Desktop Application\" when creating OAuth 2.0 credentials\r\n- The credentials file must be named exactly `credentials.json`\r\n- Keep your credentials file secure and never commit it to version control\r\n\r\n### Authentication Setup\r\n\r\n**Run the setup script:**\r\n```bash\r\npython -m mcp_colab_server.setup\r\n```\r\n\r\n**The setup process will:**\r\n- Validate your credentials file format and content\r\n- Launch a browser window for Google OAuth authentication\r\n- Save authentication tokens to `~/.mcp-colab/token.json`\r\n- Perform a connection test to verify everything works\r\n\r\n**Check configuration status:**\r\n```bash\r\npython -m mcp_colab_server.config_manager --status\r\n```\r\n\r\nThis command displays your current configuration status, authentication state, and any potential issues.\r\n\r\n### Chrome Profile Management\r\n\r\nThe system automatically manages Chrome browser profiles to maintain persistent Google login sessions:\r\n\r\n**Profile Management Commands:**\r\n```bash\r\n# View all Chrome profiles and their status\r\npython -m mcp_colab_server.config_manager --profile-summary\r\n\r\n# Optimize profiles by cleaning cache and temporary files\r\npython -m mcp_colab_server.config_manager --optimize-profiles\r\n\r\n# Remove old or unused profiles\r\npython -m mcp_colab_server.config_manager --clean-profiles\r\n```\r\n\r\n**Profile Management Benefits:**\r\n- **Persistent Authentication**: Google login sessions are remembered between server restarts\r\n- **Faster Startup Times**: No need to re-authenticate for each session\r\n- **Automatic Cleanup**: Profiles are automatically optimized to minimize disk usage\r\n- **User Isolation**: Each user maintains their own separate profile directory\r\n- **Session Recovery**: Ability to recover from browser crashes or unexpected shutdowns\r\n\r\n### MCP Integration\r\n\r\n**For Claude Desktop Application:**\r\n\r\nAdd the following configuration to your Claude desktop settings:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"google-colab-mcp\": {\r\n \"command\": \"google-colab-mcp\",\r\n \"args\": [],\r\n \"env\": {\r\n \"MCP_COLAB_LOG_LEVEL\": \"INFO\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n**For Development or Custom Setup:**\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"google-colab-mcp\": {\r\n \"command\": \"python\",\r\n \"args\": [\"-m\", \"mcp_colab_server.server\"],\r\n \"cwd\": \"/path/to/your/google-colab-mcp\",\r\n \"env\": {\r\n \"MCP_COLAB_LOG_LEVEL\": \"INFO\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n## Available Tools\r\n\r\n| Tool Name | Function | Example Usage |\r\n|-----------|----------|---------------|\r\n| `init_user_config` | Initialize user configuration directory | \"Initialize my Google Colab MCP configuration\" |\r\n| `check_auth_status` | Verify authentication and connection status | \"Check my Google authentication status\" |\r\n| `setup_google_credentials` | Get step-by-step setup instructions | \"How do I set up Google credentials?\" |\r\n| `authenticate_google` | Complete Google OAuth authentication flow | \"Authenticate with Google\" |\r\n| `create_colab_notebook` | Create a new Colab notebook | \"Create a notebook called 'Data Analysis'\" |\r\n| `list_notebooks` | List all accessible Colab notebooks | \"Show me my Colab notebooks\" |\r\n| `get_notebook_content` | Retrieve notebook content and structure | \"Show me the content of my latest notebook\" |\r\n| `run_code_cell` | Execute Python code in Colab runtime | \"Run this code: import pandas as pd\" |\r\n| `install_package` | Install Python packages in Colab | \"Install matplotlib in my notebook\" |\r\n| `upload_file_to_colab` | Upload files to Colab environment | \"Upload data.csv to my notebook\" |\r\n| `get_runtime_info` | Get Colab runtime status and information | \"What's the status of my Colab runtime?\" |\r\n| `get_session_info` | Get current session details | \"Show me my current Colab session\" |\r\n| `get_chrome_profile_info` | Get Chrome profile status and metrics | \"Check my browser profile status\" |\r\n| `clear_chrome_profile` | Reset Chrome profile and clear data | \"Clear my browser data and reset login\" |\r\n\r\n## Example Conversations\r\n\r\n**Working with AI Assistants (Claude/ChatGPT):**\r\n\r\n**Notebook Creation:**\r\n```\r\nUser: \"Create a new Colab notebook for analyzing sales data\"\r\nAI: Creates notebook and responds with notebook URL and ID\r\n```\r\n\r\n**Package Installation and Code Execution:**\r\n```\r\nUser: \"Install pandas and matplotlib, then create a simple plot\"\r\nAI: Installs packages and generates plotting code in your Colab\r\n```\r\n\r\n**Notebook Management:**\r\n```\r\nUser: \"List all my notebooks and show me the most recent one\"\r\nAI: Lists notebooks and displays the content of the latest one\r\n```\r\n\r\n**Complex Data Analysis:**\r\n```\r\nUser: \"Load my sales data, calculate monthly trends, and create a visualization\"\r\nAI: Executes multi-step data analysis workflow in Colab\r\n```\r\n\r\n## System Architecture\r\n\r\n```\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 AI Assistant \u2502\u25c4\u2500\u2500\u25ba\u2502 MCP Server \u2502\u25c4\u2500\u2500\u25ba\u2502 Google Colab \u2502\r\n\u2502 (Claude, etc.) \u2502 \u2502 (This Project) \u2502 \u2502 Notebooks \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502\r\n \u25bc\r\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n \u2502 Google Drive \u2502\r\n \u2502 API \u2502\r\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n```\r\n\r\n**Component Overview:**\r\nThe server functions as a bridge between AI assistants and Google Colab, utilizing:\r\n- **Google Drive API** for notebook management and storage operations\r\n- **Selenium WebDriver** for browser automation and code execution\r\n- **MCP Protocol** for standardized communication with AI assistants\r\n- **Chrome Profile Management** for persistent authentication sessions\r\n\r\n**Data Flow:**\r\n1. AI Assistant sends requests through MCP protocol\r\n2. Server processes requests and manages authentication\r\n3. Server interacts with Google Colab via Selenium automation\r\n4. Results are returned to AI Assistant through MCP protocol\r\n\r\n## Configuration\r\n\r\n### Server Configuration\r\n\r\nThe server uses a configuration file located at `~/.mcp-colab/server_config.json`:\r\n\r\n```json\r\n{\r\n \"selenium\": {\r\n \"browser\": \"chrome\",\r\n \"headless\": false,\r\n \"timeout\": 30,\r\n \"profile\": {\r\n \"use_persistent_profile\": true,\r\n \"profile_directory\": null,\r\n \"auto_create_profile\": true\r\n }\r\n },\r\n \"colab\": {\r\n \"execution_timeout\": 300,\r\n \"max_retries\": 3\r\n },\r\n \"logging\": {\r\n \"level\": \"INFO\"\r\n }\r\n}\r\n```\r\n\r\n### Chrome Profile Configuration\r\n\r\nThe server supports persistent Chrome profiles to maintain Google login sessions:\r\n\r\n**Key Features:**\r\n- **Automatic Login**: No need to sign in repeatedly\r\n- **Session Persistence**: Login data saved securely between sessions\r\n- **Profile Management**: Built-in tools to manage and clear profile data\r\n\r\n**Configuration Options:**\r\n- `use_persistent_profile`: Enable/disable persistent profiles (default: true)\r\n- `profile_directory`: Custom profile location (default: `~/.mcp-colab/chrome_profiles/default`)\r\n- `auto_create_profile`: Automatically create profile directory (default: true)\r\n\r\n**Management Commands:**\r\n- `get_chrome_profile_info`: Check profile status and disk usage\r\n- `clear_chrome_profile`: Clear profile data (requires re-authentication)\r\n\r\n### MCP Configuration Options\r\n\r\n**Advanced Configuration Example:**\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"google-colab-mcp\": {\r\n \"command\": \"google-colab-mcp\",\r\n \"args\": [],\r\n \"env\": {\r\n \"MCP_COLAB_LOG_LEVEL\": \"INFO\",\r\n \"MCP_COLAB_HEADLESS\": \"false\"\r\n },\r\n \"autoApprove\": [\r\n \"list_notebooks\",\r\n \"get_notebook_content\",\r\n \"get_runtime_info\"\r\n ]\r\n }\r\n }\r\n}\r\n```\r\n\r\n**Environment Variables:**\r\n- `MCP_COLAB_LOG_LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR)\r\n- `MCP_COLAB_HEADLESS`: Run Chrome in headless mode (true/false)\r\n- `MCP_COLAB_TIMEOUT`: Default timeout for operations (seconds)\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues and Solutions\r\n\r\n**Authentication Problems**\r\n```bash\r\n# Re-run the setup script to fix authentication issues\r\npython -m mcp_colab_server.setup\r\n\r\n# Clear existing tokens and re-authenticate\r\nrm ~/.mcp-colab/token.json\r\npython -m mcp_colab_server.setup\r\n\r\n# Check current authentication status\r\npython -m mcp_colab_server.config_manager --status\r\n```\r\n\r\n**Browser and WebDriver Issues**\r\n```bash\r\n# Update Chrome/Firefox to the latest version\r\n# Install or update WebDriver dependencies\r\npip install webdriver-manager --upgrade\r\npip install selenium --upgrade\r\n\r\n# Clear Chrome profiles if having persistent issues\r\npython -m mcp_colab_server.config_manager --clean-profiles\r\n```\r\n\r\n**MCP Server Connection Problems**\r\n```bash\r\n# Test if the server starts correctly\r\ngoogle-colab-mcp\r\n\r\n# Verify installation\r\npip show google-colab-mcp\r\n\r\n# Reinstall if necessary\r\npip install --force-reinstall google-colab-mcp\r\n```\r\n\r\n### Debug Mode Configuration\r\n\r\nEnable detailed logging for troubleshooting:\r\n\r\n```json\r\n{\r\n \"env\": {\r\n \"MCP_COLAB_LOG_LEVEL\": \"DEBUG\",\r\n \"MCP_COLAB_HEADLESS\": \"false\"\r\n }\r\n}\r\n```\r\n\r\n### Performance Optimization\r\n\r\n**For Better Performance:**\r\n- Use headless mode (`MCP_COLAB_HEADLESS\": \"true\"`) in production\r\n- Regularly optimize Chrome profiles using `--optimize-profiles`\r\n- Increase timeout values for slower network connections\r\n- Monitor log files for performance bottlenecks\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information.\r\n\r\n**Development Workflow:**\r\n1. Fork the repository on GitHub\r\n2. Create a feature branch: `git checkout -b feature/your-feature-name`\r\n3. Make your changes and add tests\r\n4. Commit your changes: `git commit -m 'Add amazing feature'`\r\n5. Push to the branch: `git push origin feature/your-feature-name`\r\n6. Open a Pull Request with a detailed description\r\n\r\n**Development Setup:**\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/inkbytefo/google-colab-mcp.git\r\ncd google-colab-mcp\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npython -m pytest tests/\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for complete details.\r\n\r\n## Acknowledgments\r\n\r\n- [Model Context Protocol](https://modelcontextprotocol.io/) for providing the communication standard\r\n- [Google Colab](https://colab.research.google.com/) for the cloud-based notebook platform\r\n- [Anthropic](https://www.anthropic.com/) for Claude and MCP development\r\n- The open-source community for valuable contributions and feedback\r\n\r\n## Support and Resources\r\n\r\n**Documentation and Help:**\r\n- [Project Documentation](docs/)\r\n- [Issue Tracker](https://github.com/inkbytefo/google-colab-mcp/issues)\r\n- [Community Discussions](https://github.com/inkbytefo/google-colab-mcp/discussions)\r\n- [Changelog and Updates](CHANGELOG.md)\r\n\r\n**Getting Help:**\r\n- Search existing issues before creating new ones\r\n- Provide detailed information when reporting bugs\r\n- Include log files and configuration details for faster resolution\r\n\r\n---\r\n\r\n**Project Information:**\r\n- **Author:** inkbytefo\r\n- **Version:** 1.0.1\r\n- **Repository:** [github.com/inkbytefo/google-colab-mcp](https://github.com/inkbytefo/google-colab-mcp)\r\n- **License:** MIT\r\n- **Python Version:** 3.8+\r\n\r\n*Built for the AI and Data Science community*\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Model Context Protocol server for seamless Google Colab integration with AI assistants",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/inkbytefo/google-colab-mcp/issues",
"Documentation": "https://github.com/inkbytefo/google-colab-mcp#readme",
"Homepage": "https://github.com/inkbytefo/google-colab-mcp",
"Repository": "https://github.com/inkbytefo/google-colab-mcp.git"
},
"split_keywords": [
"mcp",
" google-colab",
" ai",
" assistant",
" jupyter",
" notebook",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f3d85144d151e2b8707b6b3959ed0728b9e73b313e72b44ff6f0d7003d961fd8",
"md5": "c11fe99253408212794dec88028eaee5",
"sha256": "b597a358a08fb7e60dc664a813ce543258df8ad8594cb05ea3d59e7de22d6444"
},
"downloads": -1,
"filename": "google_colab_mcp-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c11fe99253408212794dec88028eaee5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 62584,
"upload_time": "2025-08-26T21:13:56",
"upload_time_iso_8601": "2025-08-26T21:13:56.474629Z",
"url": "https://files.pythonhosted.org/packages/f3/d8/5144d151e2b8707b6b3959ed0728b9e73b313e72b44ff6f0d7003d961fd8/google_colab_mcp-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "af1ef6900c89e321d230cd01fa30fc4c13f72d85ebcd6f160e8f54fd7fd7937e",
"md5": "bfafedbfcd28737c1b9b00470597a141",
"sha256": "11ca46ce2b6fa16ae00d308681592e678485af85cb0be5eb269bab73375eb862"
},
"downloads": -1,
"filename": "google_colab_mcp-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "bfafedbfcd28737c1b9b00470597a141",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 89979,
"upload_time": "2025-08-26T21:13:57",
"upload_time_iso_8601": "2025-08-26T21:13:57.802868Z",
"url": "https://files.pythonhosted.org/packages/af/1e/f6900c89e321d230cd01fa30fc4c13f72d85ebcd6f160e8f54fd7fd7937e/google_colab_mcp-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 21:13:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "inkbytefo",
"github_project": "google-colab-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "google-api-python-client",
"specs": [
[
">=",
"2.100.0"
]
]
},
{
"name": "google-auth-httplib2",
"specs": [
[
">=",
"0.2.0"
]
]
},
{
"name": "google-auth-oauthlib",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "selenium",
"specs": [
[
">=",
"4.15.0"
]
]
},
{
"name": "webdriver-manager",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "selenium-stealth",
"specs": [
[
">=",
"1.0.6"
]
]
},
{
"name": "undetected-chromedriver",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.12.0"
]
]
},
{
"name": "lxml",
"specs": [
[
">=",
"4.9.0"
]
]
},
{
"name": "asyncio-mqtt",
"specs": [
[
">=",
"0.11.0"
]
]
}
],
"lcname": "google-colab-mcp"
}
JSON
