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

Quick smoke test (MCP stdio)

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

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)

Configuration

Environment Variables

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

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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:

Usage

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

Creating Immediate Tasks

The assistant will:

1. Check jules://sources to find the repository

2. Call create_coding_task tool with appropriate prompt

3. Return the session ID for monitoring

Scheduling Recurring Tasks

The assistant will:

1. Call schedule_recurring_task with cron "0 9 * * 1"

2. Save the schedule to ~/.jules-mcp/schedules.json

3. Confirm the next execution time

Monitoring Progress

The assistant will:

1. Call get_session_status or read jules://sessions/abc123/full

2. Show current state (PLANNING, IN_PROGRESS, COMPLETED, etc.)

3. Provide next steps based on state

Reviewing and Approving Plans

The assistant will:

1. Read jules://sessions/abc123/full to get the plan

2. Display the plan steps to you

3. Call manage_session with action=approve_plan after your confirmation

Available Resources

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

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:

This prevents accidental modifications to production or sensitive repos.

Plan Approval Workflow

For critical repositories, always set require_plan_approval: true:

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:

"Repository not found" error

1. Check jules://sources resource to see connected repos

2. Ensure the GitHub app is installed on the repository

3. 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

Development

Project Structure

Build Commands

API Endpoints Covered

This server provides complete coverage of the Jules v1alpha API:

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)