Google Jules MCP

# Google Jules MCP A Model Context Protocol (MCP) server for automating Google Jules - the AI coding assistant. This MCP enables seamless integration with Jules for task creation, code review automation, repository management, and AI-powered development workflows. ## Features ### 🎯 **Task Management** - **Create Tasks**: Automatically create Jules tasks with repository and description - **Monitor Progress**: Track task status and get real-time updates - **Approve Plans**: Review and approve Jules execution plans - **Resume Tasks**: Resume paused or interrupted tasks - **Bulk Operations**: Create multiple tasks efficiently ### 🔧 **Code Operations** - **Code Analysis**: Analyze code changes and diffs - **Branch Management**: Handle repository branches and configurations - **Source Navigation**: Browse and analyze source files - **Review Automation**: Automate code review workflows ### 💬 **Interactive Communication** - **Send Messages**: Send instructions and feedback to Jules - **Chat History**: Track conversation history with Jules - **Context Extraction**: Extract relevant context from task discussions ### 📊 **Project Management** - **Task Listing**: List and filter tasks by status - **Progress Tracking**: Monitor development progress across projects - **Data Persistence**: Local storage of task data and history ### 🔐 **Session Management** (NEW!) - **Multiple Session Modes**: Fresh, Chrome profile, cookies, persistent, and Browserbase - **Google Authentication**: Seamless login with existing Google sessions - **Cookie Management**: Extract, save, and restore authentication cookies - **Remote Browser Support**: Use Browserbase for cloud deployments - **Cross-Platform**: Works locally and in cloud environments ## Available Tools | Tool | Description | |------|-------------| | **Task Management** || | `jules_create_task` | Create a new Jules task with repository and description | | `jules_get_task` | Get detailed information about a specific task | | `jules_send_message` | Send messages/instructions to Jules in active tasks | | `jules_approve_plan` | Approve Jules execution plans | | `jules_resume_task` | Resume paused tasks | | `jules_list_tasks` | List tasks with filtering options | | `jules_analyze_code` | Analyze code changes and project structure | | `jules_bulk_create_tasks` | Create multiple tasks from a list | | **Session & Authentication** || | `jules_get_cookies` | Get current browser cookies for session persistence | | `jules_set_cookies` | Set browser cookies from string/JSON for authentication | | `jules_session_info` | Get current session configuration and status | | **Debugging** || | `jules_screenshot` | Take debugging screenshots | ## Installation ### Prerequisites - Node.js 18+ - TypeScript - Git access to repositories you want to manage ### Setup ```bash # Clone the repository git clone https://github.com/samihalawa/google-jules-mcp.git cd google-jules-mcp # Install dependencies npm install # Build the project npm run build # Test the installation npm test ``` ## 🔐 Session Management & Authentication ### Session Modes The MCP supports 5 different session management modes: | Mode | Description | Use Case | |------|-------------|----------| | `fresh` | New browser session each time | Testing, no authentication needed | | `chrome-profile` | Use existing Chrome profile | Local development with existing Google login | | `cookies` | Save/load cookies to file | Persistent authentication without full profile | | `persistent` | Save browser data to directory | Local development with full session persistence | | `browserbase` | Remote browser session | Cloud deployments, Smithery hosting | ### Configuration Options #### 🌐 **Browserbase (Recommended for Smithery)** Perfect for remote deployments and cloud hosting: ```bash SESSION_MODE=browserbase BROWSERBASE_API_KEY=bb_live_g3i-b4WPFh__E3cErKE5rO-jWds # Your API key BROWSERBASE_PROJECT_ID=d718e85f-be7b-497d-9123-b1bbf798f1bb # Your project ID BROWSERBASE_SESSION_ID= # Optional: use existing session ``` #### 🍪 **Cookie Authentication (Best for Manual Setup)** Extract cookies from your browser and set them as environment variable: ```bash SESSION_MODE=cookies GOOGLE_AUTH_COOKIES="session_id=abc123; domain=.google.com; auth_token=xyz789; domain=.google.com" COOKIES_PATH=~/.jules-mcp/cookies.json # File to save/load cookies ``` #### 🌍 **Chrome Profile (Local Development)** Use your existing Chrome profile: ```bash SESSION_MODE=chrome-profile CHROME_USER_DATA_DIR=/Users/yourname/Library/Application Support/Google/Chrome/Default ``` #### 💾 **Persistent Browser Data** Save browser data to a specific directory: ```bash SESSION_MODE=persistent CHROME_USER_DATA_DIR=~/.jules-mcp/browser-data # Custom browser data directory ``` ### How to Get Google Authentication Cookies 1. **Log in to Jules**: Visit https://jules.google.com and log in 2. **Open Developer Tools**: Press F12 or Cmd+Option+I 3. **Go to Application/Storage tab** 4. **Find Cookies**: Look for `.google.com` cookies 5. **Copy Important Cookies**: Look for cookies like: - `session_id` or `sessionid` - `auth_token` or `authuser` - `SID`, `HSID`, `SSID` - `SAPISID`, `APISID` **Format for environment variable:** ```bash GOOGLE_AUTH_COOKIES="cookie1=value1; domain=.google.com; cookie2=value2; domain=.google.com" ``` ### Environment Configuration Create a `.env` file or set environment variables: ```bash # Browser Configuration HEADLESS=true # Run browser in headless mode TIMEOUT=30000 # Browser timeout in milliseconds DEBUG=false # Enable debug mode with screenshots # Session Management SESSION_MODE=browserbase # fresh | chrome-profile | cookies | persistent | browserbase # Browserbase Configuration (for remote/cloud deployments) BROWSERBASE_API_KEY=your_api_key BROWSERBASE_PROJECT_ID=your_project_id BROWSERBASE_SESSION_ID=optional_existing_session # Cookie Authentication GOOGLE_AUTH_COOKIES="session_id=abc; domain=.google.com" COOKIES_PATH=~/.jules-mcp/cookies.json # Chrome Profile (local development) CHROME_USER_DATA_DIR=/path/to/chrome/profile # Data Storage JULES_DATA_PATH=~/.jules-mcp/data.json # Custom data storage path ``` ## Usage Examples ### 1. Create a New Task ```javascript // Create a task to fix a bug { "name": "jules_create_task", "arguments": { "description": "Fix the login authentication bug in the user dashboard. The issue occurs when users try to log in with special characters in their password.", "repository": "mycompany/webapp", "branch": "main" } } ``` ### 2. Monitor Task Progress ```javascript // Get task details and progress { "name": "jules_get_task", "arguments": { "taskId": "9103172019911831130" } } ``` ### 3. Send Instructions to Jules ```javascript // Send additional context or instructions { "name": "jules_send_message", "arguments": { "taskId": "9103172019911831130", "message": "Please also add unit tests for the authentication fix and ensure backward compatibility." } } ``` ### 4. Bulk Task Creation ```javascript // Create multiple tasks at once { "name": "jules_bulk_create_tasks", "arguments": { "tasks": [ { "description": "Add dark mode support to the UI", "repository": "mycompany/frontend", "branch": "feature/dark-mode" }, { "description": "Optimize database queries for user search", "repository": "mycompany/backend", "branch": "performance/search" } ] } } ``` ### 5. List and Filter Tasks ```javascript // List active tasks { "name": "jules_list_tasks", "arguments": { "status": "in_progress", "limit": 10 } } ``` ### 6. Session Management Examples #### Check Session Status ```javascript { "name": "jules_session_info", "arguments": {} } ``` #### Get Current Cookies (for backup) ```javascript { "name": "jules_get_cookies", "arguments": { "format": "string" // or "json" } } ``` #### Set Authentication Cookies ```javascript { "name": "jules_set_cookies", "arguments": { "cookies": "session_id=abc123; domain=.google.com; auth_token=xyz789; domain=.google.com", "format": "string" } } ``` ## MCP Resources The server provides useful resources for context: - `jules://schemas/task` - Complete task data model - `jules://current/active-tasks` - Live list of active tasks - `jules://templates/common-tasks` - Template examples for common development tasks ## Common Task Templates The MCP includes templates for common development scenarios: - **Bug Fix**: `"Fix the [specific issue] in [filename]. The problem is [description]."` - **Feature Add**: `"Add [feature name] functionality to [location]. Requirements: [list requirements]."` - **Refactor**: `"Refactor [component/function] to improve [performance/readability/maintainability]."` - **Testing**: `"Add comprehensive tests for [component/function] covering [test cases]."` - **Documentation**: `"Update documentation for [component] to include [new features/changes]."` ## Integration with Claude Code ### Local Integration ```json { "mcpServers": { "google-jules-mcp": { "command": "node", "args": ["path/to/google-jules-mcp/dist/index.js"], "env": { "HEADLESS": "true", "SESSION_MODE": "cookies", "GOOGLE_AUTH_COOKIES": "your_cookies_here", "DEBUG": "false" } } } } ``` ## 🌐 Smithery Deployment ### Deploy to Smithery.ai The MCP is fully configured for Smithery deployment with comprehensive session management: 1. **Fork/Clone** this repository 2. **Deploy to Smithery**: Visit [smithery.ai](https://smithery.ai) and connect your repo 3. **Configure Session Management** in Smithery settings: #### Option A: Browserbase (Recommended) ```bash SESSION_MODE=browserbase BROWSERBASE_API_KEY=bb_live_g3i-b4WPFh__E3cErKE5rO-jWds BROWSERBASE_PROJECT_ID=d718e85f-be7b-497d-9123-b1bbf798f1bb ``` #### Option B: Cookie Authentication ```bash SESSION_MODE=cookies GOOGLE_AUTH_COOKIES="session_id=abc123; domain=.google.com; auth_token=xyz789; domain=.google.com" ``` 4. **Access Remotely**: Use your deployed MCP from any Claude Code instance ### Benefits of Smithery + Browserbase - ✅ **No Local Browser**: Runs entirely in the cloud - ✅ **Persistent Sessions**: Maintain Google authentication across deployments - ✅ **Global Access**: Use from anywhere with internet connection - ✅ **Auto-scaling**: Handles multiple concurrent requests - ✅ **Zero Setup**: No local dependencies or configuration needed ## Troubleshooting ### Common Issues 1. **Browser Automation Fails** - Ensure you have proper access to `jules.google.com` - Check if you're logged into your Google account - Try running with `HEADLESS=false` to see what's happening 2. **Task Creation Fails** - Verify repository names are correct (`owner/repo-name` format) - Ensure you have access to the specified repositories - Check that branches exist 3. **Permission Errors** - Make sure you have write access to the data storage path - Verify repository permissions in GitHub ### Debug Mode Enable debug mode for troubleshooting: ```bash DEBUG=true HEADLESS=false npm start ``` This will: - Show browser interactions visually - Take screenshots on errors - Provide detailed logging ## Development ### Project Structure ``` google-jules-mcp/ ├── src/ │ └── index.ts # Main MCP server implementation ├── docs/ │ └── referencerecordings/ # Browser automation references ├── scripts/ │ └── test-mcp.js # Testing script ├── dist/ # Compiled output ├── package.json ├── tsconfig.json └── smithery.yaml # MCP deployment config ``` ### Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ### Testing ```bash # Run the test suite npm test # Build and test npm run build && npm test # Development mode with file watching npm run dev ``` ## Architecture The MCP follows established patterns: - **Browser Automation**: Uses Playwright for reliable web automation - **Data Persistence**: Local JSON storage for task tracking - **Error Handling**: Comprehensive error handling with meaningful messages - **Resource Management**: Proper browser lifecycle management - **Security**: No credential storage, relies on browser session ## Workflow Integration This MCP is designed to integrate with development workflows: 1. **Issue Tracking → Jules Tasks**: Convert GitHub issues to Jules tasks 2. **Code Review → Automation**: Automate code review processes 3. **CI/CD Integration**: Trigger Jules tasks from deployment pipelines 4. **Team Collaboration**: Share Jules task management across teams ## License MIT License - see LICENSE file for details. ## Acknowledgments - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) - Inspired by the tusclasesparticulares-mcp implementation patterns - Browser automation powered by [Playwright](https://playwright.dev/) --- **Note**: This MCP requires access to Google Jules. Ensure you have appropriate permissions and access to the repositories you want to manage.