Jules MCP Server

A production-ready Model Context Protocol (MCP) server for the Google Jules API, enabling autonomous coding tasks and scheduling directly from AI assistants like Claude.

⚠️ DISCLAIMER: This is an independent, open-source project and is NOT officially created, maintained, or endorsed by Google. This server is a community-driven integration with the public Jules API. Use at your own risk. For official Jules documentation, visit jules.google.

🌟 Star This Repository

If you find this useful, please star ⭐ the repository to help others discover it!

Overview

This MCP server bridges the Google Jules coding agent with AI assistants, allowing you to:

Create coding tasks - Delegate bug fixes, refactoring, tests, and features to Jules
Schedule recurring tasks - Set up automated weekly/daily maintenance (dependency updates, security audits, etc.)
Monitor progress - Track session states and review generated plans
Approve plans - Human-in-the-loop control before code changes
Manage workflows - Send feedback and iterate on Jules's work

Architecture: The "Thick Server" Pattern

Since the Jules API v1alpha is stateless (no native scheduling endpoints), this server implements a local scheduling engine:

Persistent Storage: Schedules stored in ~/.jules-mcp/schedules.json
Cron Engine: Uses node-schedule for reliable task execution
Survives Restarts: Schedules are rehydrated on server startup
Autonomous Execution: Scheduled tasks run even without active IDE sessions

Installation

Prerequisites

Node.js 18.0.0 or higher
Jules API Key - Generate at jules.google/settings
GitHub Repositories - Connect repos to Jules via the web UI first

Setup

# Clone or download this repository
cd jules-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Set your API key
export JULES_API_KEY="your-key-here"

# Test the server
npm start

Quick smoke test (MCP stdio)

After building and setting JULES_API_KEY, you can validate the server end-to-end:

npm run mcp:smoke

Expected output (with a valid key):

Lists 6 tools, 5 prompts, and the 4 core resources
Attempts to read a fake session ID and reports a Jules 404 (proves real API calls work)
Attempts a tool call with dummy data and reports the API error without crashing

Global Installation (Recommended)

# Install globally
npm install -g

# Now available as: jules-mcp
jules-mcp

Configuration

Environment Variables

Create a .env file or set these in your shell:

# Required
JULES_API_KEY=your_jules_api_key_here

# Optional - Security allowlist (comma-separated repo names)
# If set, only these repos can be modified
JULES_ALLOWED_REPOS=owner/repo1,owner/repo2

# Optional - Default branch
JULES_DEFAULT_BRANCH=main

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jules": {
      "command": "node",
      "args": ["/path/to/jules-mcp/dist/index.js"],
      "env": {
        "JULES_API_KEY": "your-key-here"
      }
    }
  }
}

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

VS Code / Cursor Configuration

For Cursor or VS Code with MCP support:

{
  "mcp.servers": {
    "jules": {
      "command": "jules-mcp",
      "env": {
        "JULES_API_KEY": "your-key-here"
      }
    }
  }
}

Usage

Once configured, your AI assistant can use Jules through natural language:

Creating Immediate Tasks

"Use Jules to add unit tests for the authentication module in my-app-backend repository"

The assistant will:

Check jules://sources to find the repository
Call create_coding_task tool with appropriate prompt
Return the session ID for monitoring

Scheduling Recurring Tasks

"Schedule Jules to update dependencies every Monday at 9 AM in my-app-backend"

The assistant will:

Call schedule_recurring_task with cron "0 9 * * 1"
Save the schedule to ~/.jules-mcp/schedules.json
Confirm the next execution time

Monitoring Progress

"Check the status of Jules session abc123"

The assistant will:

Call get_session_status or read jules://sessions/abc123/full
Show current state (PLANNING, IN_PROGRESS, COMPLETED, etc.)
Provide next steps based on state

Reviewing and Approving Plans

"Show me Jules's plan for session abc123 and approve it"

The assistant will:

Read jules://sessions/abc123/full to get the plan
Display the plan steps to you
Call manage_session with action=approve_plan after your confirmation

Available Resources

Resources are read-only context that the AI can access:

URI	Description
`jules://sources`	Connected GitHub repositories
`jules://sessions/list`	Recent Jules sessions
`jules://sessions/{id}/full`	Complete session details with activities
`jules://schedules`	Active scheduled tasks
`jules://schedules/history`	Execution history

Available Tools

Tools are actions the AI can execute:

create_coding_task

Creates an immediate Jules coding session.

Parameters:

prompt (required) - Natural language task instruction
source (required) - Repository (format: sources/github/owner/repo)
branch (optional) - Target branch (default: main)
auto_create_pr (optional) - Auto-create PR (default: true)
require_plan_approval (optional) - Pause for review (default: false)
title (optional) - Session title

Returns: Session ID and monitoring URL

manage_session

Manage active sessions (approve plans, send feedback).

Parameters:

session_id (required)
action (required) - "approve_plan" or "send_message"
message (optional) - Required for send_message

get_session_status

Check session status and get next steps.

Parameters:

session_id (required)

schedule_recurring_task

Schedule a task to run on a cron schedule.

Parameters:

task_name (required) - Unique schedule identifier
cron_expression (required) - Standard cron format
prompt (required) - Task instruction
source (required) - Repository resource name
branch, auto_create_pr, require_plan_approval, timezone (optional)

Cron Examples:

"0 9 * * 1" - Every Monday at 9 AM
"0 2 * * *" - Every day at 2 AM
"0 0 1 * *" - First day of each month at midnight

list_schedules

List all active scheduled tasks with next run times.

delete_schedule

Remove a scheduled task.

Parameters:

task_name (required)

Available Prompts

Prompts are templates that guide best practices:

refactor_module - Guided refactoring workflow
setup_weekly_maintenance - Automated maintenance setup
audit_security - Comprehensive security audit
fix_failing_tests - Test failure resolution
update_dependencies - Dependency update with breaking change handling

Security Considerations

API Key Security

Never commit your JULES_API_KEY to version control
Store in environment variables or secure secrets manager
The API key grants write access to connected repositories

Repository Allowlist

Use JULES_ALLOWED_REPOS to restrict which repositories can be modified:

export JULES_ALLOWED_REPOS="myorg/safe-repo,myorg/test-repo"

This prevents accidental modifications to production or sensitive repos.

Plan Approval Workflow

For critical repositories, always set require_plan_approval: true:

"Create a task but require plan approval before any code changes"

This ensures human review before Jules modifies code.

Audit Logging

All scheduled task executions are logged to jules://schedules/history. Review this regularly to audit autonomous activities.

Troubleshooting

"JULES_API_KEY environment variable is required"

Set your API key:

export JULES_API_KEY="your-key-here"

"Repository not found" error

Check jules://sources resource to see connected repos
Ensure the GitHub app is installed on the repository
Use the exact resource name format: sources/github/owner/repo

Schedules not persisting

Check that ~/.jules-mcp/schedules.json exists and is writable.

TypeScript compilation errors

npm run typecheck

Development

Project Structure

src/
  types/          # TypeScript type definitions
    jules-api.ts  # Jules API types
    schedule.ts   # Schedule types
  api/            # API client layer
    jules-client.ts
  storage/        # Persistence layer
    schedule-store.ts
  scheduler/      # Cron engine
    cron-engine.ts
  mcp/            # MCP protocol layer
    resources.ts  # Resources implementation
    tools.ts      # Tools implementation
    prompts.ts    # Prompt templates
  index.ts        # Main entry point

Build Commands

npm run build      # Compile TypeScript
npm run dev        # Development mode with tsx
npm run typecheck  # Type checking only

API Endpoints Covered

This server provides complete coverage of the Jules v1alpha API:

Endpoint	Method	MCP Mapping
`/sources`	GET	Resource: `jules://sources`
`/sources/{name}`	GET	Included in full session resource
`/sessions`	POST	Tool: `create_coding_task`
`/sessions`	GET	Resource: `jules://sessions/list`
`/sessions/{id}`	GET	Tool: `get_session_status`
`/sessions/{id}:approvePlan`	POST	Tool: `manage_session` (approve_plan)
`/sessions/{id}:sendMessage`	POST	Tool: `manage_session` (send_message)
`/sessions/{id}/activities`	GET	Resource: `jules://sessions/{id}/full`

Additional Capabilities (Beyond API)

Local scheduling - Cron-based task execution
Schedule persistence - Survives server restarts
Execution history - Audit trail for scheduled tasks

Future Roadmap

When Jules API adds native scheduling:

The schedule_recurring_task tool will migrate from local cron to API calls
Existing local schedules can be migrated automatically
The MCP tool interface remains unchanged for backward compatibility

Resources

Jules API Documentation: https://developers.google.com/jules/api
Jules Web Interface: https://jules.google
Model Context Protocol: https://modelcontextprotocol.io
MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

License

MIT

Contributing

This is an open-source implementation. Contributions welcome for:

Additional prompt templates
Enhanced error handling
Webhook support (when Jules API adds it)
Advanced scheduling features (conditional execution, dependency chains)

Jules MCP Server

A production-ready Model Context Protocol (MCP) server for the Google Jules API, enabling autonomous coding tasks and scheduling directly from AI assistants like Claude.

⚠️ DISCLAIMER: This is an independent, open-source project and is NOT officially created, maintained, or endorsed by Google. This server is a community-driven integration with the public Jules API. Use at your own risk. For official Jules documentation, visit jules.google.

🌟 Star This Repository

If you find this useful, please star ⭐ the repository to help others discover it!

Overview

This MCP server bridges the Google Jules coding agent with AI assistants, allowing you to:

Create coding tasks - Delegate bug fixes, refactoring, tests, and features to Jules
Schedule recurring tasks - Set up automated weekly/daily maintenance (dependency updates, security audits, etc.)
Monitor progress - Track session states and review generated plans
Approve plans - Human-in-the-loop control before code changes
Manage workflows - Send feedback and iterate on Jules's work

Architecture: The "Thick Server" Pattern

Since the Jules API v1alpha is stateless (no native scheduling endpoints), this server implements a local scheduling engine:

Persistent Storage: Schedules stored in ~/.jules-mcp/schedules.json
Cron Engine: Uses node-schedule for reliable task execution
Survives Restarts: Schedules are rehydrated on server startup
Autonomous Execution: Scheduled tasks run even without active IDE sessions

Installation

Prerequisites

Node.js 18.0.0 or higher
Jules API Key - Generate at jules.google/settings
GitHub Repositories - Connect repos to Jules via the web UI first

Setup

# Clone or download this repository
cd jules-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Set your API key
export JULES_API_KEY="your-key-here"

# Test the server
npm start

Quick smoke test (MCP stdio)

After building and setting JULES_API_KEY, you can validate the server end-to-end:

npm run mcp:smoke

Expected output (with a valid key):

Lists 6 tools, 5 prompts, and the 4 core resources
Attempts to read a fake session ID and reports a Jules 404 (proves real API calls work)
Attempts a tool call with dummy data and reports the API error without crashing

Global Installation (Recommended)

# Install globally
npm install -g

# Now available as: jules-mcp
jules-mcp

Configuration

Environment Variables

Create a .env file or set these in your shell:

# Required
JULES_API_KEY=your_jules_api_key_here

# Optional - Security allowlist (comma-separated repo names)
# If set, only these repos can be modified
JULES_ALLOWED_REPOS=owner/repo1,owner/repo2

# Optional - Default branch
JULES_DEFAULT_BRANCH=main

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jules": {
      "command": "node",
      "args": ["/path/to/jules-mcp/dist/index.js"],
      "env": {
        "JULES_API_KEY": "your-key-here"
      }
    }
  }
}

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

VS Code / Cursor Configuration

For Cursor or VS Code with MCP support:

{
  "mcp.servers": {
    "jules": {
      "command": "jules-mcp",
      "env": {
        "JULES_API_KEY": "your-key-here"
      }
    }
  }
}

Usage

Once configured, your AI assistant can use Jules through natural language:

Creating Immediate Tasks

"Use Jules to add unit tests for the authentication module in my-app-backend repository"

The assistant will:

Check jules://sources to find the repository
Call create_coding_task tool with appropriate prompt
Return the session ID for monitoring

Scheduling Recurring Tasks

"Schedule Jules to update dependencies every Monday at 9 AM in my-app-backend"

The assistant will:

Call schedule_recurring_task with cron "0 9 * * 1"
Save the schedule to ~/.jules-mcp/schedules.json
Confirm the next execution time

Monitoring Progress

"Check the status of Jules session abc123"

The assistant will:

Call get_session_status or read jules://sessions/abc123/full
Show current state (PLANNING, IN_PROGRESS, COMPLETED, etc.)
Provide next steps based on state

Reviewing and Approving Plans

"Show me Jules's plan for session abc123 and approve it"

The assistant will:

Read jules://sessions/abc123/full to get the plan
Display the plan steps to you
Call manage_session with action=approve_plan after your confirmation

Available Resources

Resources are read-only context that the AI can access:

URI	Description
`jules://sources`	Connected GitHub repositories
`jules://sessions/list`	Recent Jules sessions
`jules://sessions/{id}/full`	Complete session details with activities
`jules://schedules`	Active scheduled tasks
`jules://schedules/history`	Execution history

Available Tools

Tools are actions the AI can execute:

create_coding_task

Creates an immediate Jules coding session.

Parameters:

prompt (required) - Natural language task instruction
source (required) - Repository (format: sources/github/owner/repo)
branch (optional) - Target branch (default: main)
auto_create_pr (optional) - Auto-create PR (default: true)
require_plan_approval (optional) - Pause for review (default: false)
title (optional) - Session title

Returns: Session ID and monitoring URL

manage_session

Manage active sessions (approve plans, send feedback).

Parameters:

session_id (required)
action (required) - "approve_plan" or "send_message"
message (optional) - Required for send_message

get_session_status

Check session status and get next steps.

Parameters:

session_id (required)

schedule_recurring_task

Schedule a task to run on a cron schedule.

Parameters:

task_name (required) - Unique schedule identifier
cron_expression (required) - Standard cron format
prompt (required) - Task instruction
source (required) - Repository resource name
branch, auto_create_pr, require_plan_approval, timezone (optional)

Cron Examples:

"0 9 * * 1" - Every Monday at 9 AM
"0 2 * * *" - Every day at 2 AM
"0 0 1 * *" - First day of each month at midnight

list_schedules

List all active scheduled tasks with next run times.

delete_schedule

Remove a scheduled task.

Parameters:

task_name (required)

Available Prompts

Prompts are templates that guide best practices:

refactor_module - Guided refactoring workflow
setup_weekly_maintenance - Automated maintenance setup
audit_security - Comprehensive security audit
fix_failing_tests - Test failure resolution
update_dependencies - Dependency update with breaking change handling

Security Considerations

API Key Security

Never commit your JULES_API_KEY to version control
Store in environment variables or secure secrets manager
The API key grants write access to connected repositories

Repository Allowlist

Use JULES_ALLOWED_REPOS to restrict which repositories can be modified:

export JULES_ALLOWED_REPOS="myorg/safe-repo,myorg/test-repo"

This prevents accidental modifications to production or sensitive repos.

Plan Approval Workflow

For critical repositories, always set require_plan_approval: true:

"Create a task but require plan approval before any code changes"

This ensures human review before Jules modifies code.

Audit Logging

All scheduled task executions are logged to jules://schedules/history. Review this regularly to audit autonomous activities.

Troubleshooting

"JULES_API_KEY environment variable is required"

Set your API key:

export JULES_API_KEY="your-key-here"

"Repository not found" error

Check jules://sources resource to see connected repos
Ensure the GitHub app is installed on the repository
Use the exact resource name format: sources/github/owner/repo

Schedules not persisting

Check that ~/.jules-mcp/schedules.json exists and is writable.

TypeScript compilation errors

npm run typecheck

Development

Project Structure

src/
  types/          # TypeScript type definitions
    jules-api.ts  # Jules API types
    schedule.ts   # Schedule types
  api/            # API client layer
    jules-client.ts
  storage/        # Persistence layer
    schedule-store.ts
  scheduler/      # Cron engine
    cron-engine.ts
  mcp/            # MCP protocol layer
    resources.ts  # Resources implementation
    tools.ts      # Tools implementation
    prompts.ts    # Prompt templates
  index.ts        # Main entry point

Build Commands

npm run build      # Compile TypeScript
npm run dev        # Development mode with tsx
npm run typecheck  # Type checking only

API Endpoints Covered

This server provides complete coverage of the Jules v1alpha API:

Endpoint	Method	MCP Mapping
`/sources`	GET	Resource: `jules://sources`
`/sources/{name}`	GET	Included in full session resource
`/sessions`	POST	Tool: `create_coding_task`
`/sessions`	GET	Resource: `jules://sessions/list`
`/sessions/{id}`	GET	Tool: `get_session_status`
`/sessions/{id}:approvePlan`	POST	Tool: `manage_session` (approve_plan)
`/sessions/{id}:sendMessage`	POST	Tool: `manage_session` (send_message)
`/sessions/{id}/activities`	GET	Resource: `jules://sessions/{id}/full`

Additional Capabilities (Beyond API)

Local scheduling - Cron-based task execution
Schedule persistence - Survives server restarts
Execution history - Audit trail for scheduled tasks

Future Roadmap

When Jules API adds native scheduling:

The schedule_recurring_task tool will migrate from local cron to API calls
Existing local schedules can be migrated automatically
The MCP tool interface remains unchanged for backward compatibility

Resources

Jules API Documentation: https://developers.google.com/jules/api
Jules Web Interface: https://jules.google
Model Context Protocol: https://modelcontextprotocol.io
MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

License

MIT

Contributing

This is an open-source implementation. Contributions welcome for:

Additional prompt templates
Enhanced error handling
Webhook support (when Jules API adds it)
Advanced scheduling features (conditional execution, dependency chains)