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

# 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:

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:

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:

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:

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:

GOOGLE_AUTH_COOKIES="cookie1=value1; domain=.google.com; cookie2=value2; domain=.google.com"

Environment Configuration

Create a .env file or set environment variables:

# 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

// 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

// Get task details and progress
{
  "name": "jules_get_task",
  "arguments": {
    "taskId": "9103172019911831130"
  }
}

3. Send Instructions to Jules

// 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

// 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

// List active tasks
{
  "name": "jules_list_tasks",
  "arguments": {
    "status": "in_progress",
    "limit": 10
  }
}

6. Session Management Examples

Check Session Status

{
  "name": "jules_session_info",
  "arguments": {}
}

Get Current Cookies (for backup)

{
  "name": "jules_get_cookies",
  "arguments": {
    "format": "string"  // or "json"
  }
}

Set Authentication Cookies

{
  "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

{
  "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 and connect your repo
3. Configure Session Management in Smithery settings:

Option A: Browserbase (Recommended)

SESSION_MODE=browserbase
BROWSERBASE_API_KEY=bb_live_g3i-b4WPFh__E3cErKE5rO-jWds
BROWSERBASE_PROJECT_ID=d718e85f-be7b-497d-9123-b1bbf798f1bb

Option B: Cookie Authentication

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:

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

# 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
• Inspired by the tusclasesparticulares-mcp implementation patterns
• Browser automation powered by Playwright

---

Note: This MCP requires access to Google Jules. Ensure you have appropriate permissions and access to the repositories you want to manage.