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

Log in to Jules: Visit https://jules.google.com and log in
Open Developer Tools: Press F12 or Cmd+Option+I
Go to Application/Storage tab
Find Cookies: Look for .google.com cookies
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:

Fork/Clone this repository
Deploy to Smithery: Visit smithery.ai and connect your repo
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"

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

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
Task Creation Fails
- Verify repository names are correct (owner/repo-name format)
- Ensure you have access to the specified repositories
- Check that branches exist
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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:

Issue Tracking → Jules Tasks: Convert GitHub issues to Jules tasks
Code Review → Automation: Automate code review processes
CI/CD Integration: Trigger Jules tasks from deployment pipelines
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.

Deploy Server

HTTP connection URL

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

Enables automation of Google Jules AI coding assistant through task creation, code review automation, repository management, and AI-powered development workflows. Supports multiple session modes including cloud deployment with persistent authentication.