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

• 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

• npm 9.0.0 or higher

• Jules API Key - Generate at jules.google/settings

• GitHub Repositories - Ensure your repositories are connected to Jules and the GitHub app is installed.

Developer Setup

# 1. Clone the repository
git clone https://github.com/savethepolarbears/jules-mcp-server.git
cd jules-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
# Copy example env and fill in your JULES_API_KEY
cp .env.example .env

# 4. Build the project
npm run build

# 5. Run a smoke test to verify connectivity
npm run mcp:smoke

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 11 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 - Your Jules API Key
JULES_API_KEY=your_jules_api_key_here

# Strongly Recommended - Encryption key for local schedules
# Using JULES_API_KEY as fallback means rotating your API key will make all scheduled tasks unreadable.
# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
JULES_ENCRYPTION_KEY=your_strong_random_key_here

# Required for create_coding_task. Comma-separated list of authorized repositories.
JULES_ALLOWED_REPOS=owner/repo1,owner/repo2

# Optional - Default branch for coding tasks
JULES_DEFAULT_BRANCH=main

Security & Privacy

This server is designed with a "security-first" approach to protect your repositories and data:

• Restrictive File Permissions: Local schedule storage (~/.jules-mcp) uses 0o700 directory permissions and 0o600 file permissions, ensuring only the owner can read or write task data.

• Encrypted Local State: All scheduled tasks are stored using AES-256-GCM encryption. A unique, random 16-byte salt is generated for every write operation to prevent offline attacks and ensure data integrity.

• PII Leak Prevention: Raw Jules API responses are sanitized and truncated (max 500 characters) before being included in logs or exceptions, preventing accidental disclosure of proprietary code or personal information in system logs.

• Generic Validation Errors: The server returns generic error messages when repository validation fails, preventing the enumeration of your private repository allowlist.

• Human-in-the-Loop: Use the require_plan_approval: true flag to ensure Jules never modifies code without your explicit review and approval of the generated plan.

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:

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

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

The assistant will:

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

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

3. Confirm the next execution time

Monitoring Progress

"Check the status of Jules session abc123"

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

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

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

Migration Guide

The server has migrated from plain JSON storage (schedules.json) to encrypted storage (schedules.enc).

• Auto-Migration: Upon startup, if schedules.json is detected, the server automatically encrypts its contents and saves them to schedules.enc, then deletes the unencrypted file.

• Backwards Compatibility: No manual action is required if you are upgrading from a version that used schedules.json.

Documentation

Detailed documentation has been moved to the docs/ folder:

• API Reference - Complete details on available MCP Tools, Resources, and Prompts.

• Architecture - System design and the "Thick Server" pattern.

• Configuration - Environment variables and setup instructions.

• Examples - Example workflows and usage patterns.

• Quickstart - A fast guide to getting up and running.

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.

Safe OpenClaw/Codex Integration

When integrating with autonomous AI agents like OpenClaw or Codex, additional safety measures are enforced:

1. Auto-PR Defaults: Prompt templates now encourage setting auto_create_pr: true to ensure all AI-driven changes are reviewed as Pull Requests before merging.

2. Mandatory Review: It is strongly recommended to set require_plan_approval: true for tasks generated by other AI systems to establish trust before allowing direct changes.

3. Quota-Aware Scheduling: To respect API limits and prevent unintended runaway tasks, the cron engine validates all schedules. Schedules must not run more frequently than once per hour. Daily or weekly intervals are highly recommended for automated maintenance.

4. Resilient Storage: Local schedules are saved using atomic file writes with corrupted-state backups to prevent the server from crashing during unexpected failures.

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

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.enc exists and is writable.

TypeScript compilation errors

npm run typecheck

Development

Documentation

This project uses JSDoc for comprehensive code documentation. Every public function, method, and class is documented with clear descriptions of purpose, parameters, and return values.

To explore the architecture and API details, check the docs/ directory.

Testing

We use Vitest for unit and integration testing.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Project Structure

src/
  types/          # TypeScript type definitions (Jules API & local state)
  api/            # Jules API client layer with retry logic
  storage/        # Secure persistence layer (encrypted JSON)
  scheduler/      # Cron engine for recurring task management
  mcp/            # MCP protocol layer (tools, resources, prompts)
  utils/          # Security, rate limiting, and string utilities
  index.ts        # Server entry point and MCP handler setup
pieces/           # Activepieces integration (Google Jules piece)

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:

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)