Jules MCP Server

A Model Context Protocol (MCP) server for the Google Jules API. This server enables LLM applications to interact with Jules - Google's AI coding assistant - to create sessions, send messages, and manage coding tasks programmatically.

Features

• List Sources: Browse available GitHub repositories connected to Jules
• Create Sessions: Start new coding tasks with Jules
• Send Messages: Communicate with Jules during active sessions
• Approve Plans: Approve Jules's proposed plans before execution
• List Activities: View the work history and conversation for a session
• Create Pull Requests: Convenience tool to create sessions that result in PRs

Prerequisites

• Python 3.10+
• A Jules API key (generate one from the Jules Settings page)
• GitHub repositories installed in Jules

Installation

Using uv (Recommended)

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

# Install dependencies with uv
uv sync

Using pip

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install fastmcp httpx pydantic

Configuration

Set the JULES_API_KEY environment variable with your API key:

export JULES_API_KEY="your-api-key-here"

Usage

Running Standalone

# With uv
uv run python main.py

# With pip/venv
python main.py

MCP Configuration

Add this server to your MCP client configuration. Below are examples for different setups.

Claude Desktop / Claude Code

Add to your mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "jules": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jules-mcp",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "JULES_API_KEY": "your-jules-api-key"
      }
    }
  }
}

Alternative (without uv)

{
  "mcpServers": {
    "jules": {
      "command": "/absolute/path/to/jules-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/jules-mcp/main.py"
      ],
      "env": {
        "JULES_API_KEY": "your-jules-api-key"
      }
    }
  }
}

Available Tools

list_sources

List available GitHub repositories that Jules can work with.

Parameters:

• page_size (int, optional): Number of sources to return (1-100, default 30)
• page_token (str, optional): Pagination token

get_source

Get details about a specific source repository.

Parameters:

• source_name (str, required): Resource name (e.g., "sources/github/owner/repo")

list_sessions

List Jules sessions (coding tasks).

Parameters:

• page_size (int, optional): Number of sessions to return (1-100, default 30)
• page_token (str, optional): Pagination token
• active_only (bool, optional): Filter to only show active sessions

get_session

Get details about a specific session.

Parameters:

• session_name (str, required): Resource name (e.g., "sessions/abc123")

create_session

Create a new Jules session to work on a coding task.

Parameters:

• prompt (str, required): The coding task description
• source (str, required): Resource name of the repository
• branch (str, optional): Branch to use
• title (str, optional): Session title
• require_plan_approval (bool, optional): Wait for plan approval before executing

send_message

Send a follow-up message to an active session.

Parameters:

• session_name (str, required): Resource name of the session
• message (str, required): Message to send

approve_plan

Approve Jules's plan for a session in AWAITING_PLAN_APPROVAL state.

Parameters:

• session_name (str, required): Resource name of the session

list_activities

List activities (work history) for a session.

Parameters:

• session_name (str, required): Resource name of the session
• page_size (int, optional): Number of activities to return (1-100, default 50)
• page_token (str, optional): Pagination token

create_pull_request

Create a session that will result in a pull request.

Parameters:

• prompt (str, required): Description of changes to make
• source (str, required): Resource name of the repository
• branch (str, optional): Base branch for the PR
• title (str, optional): Title for the session/PR

Session States

Sessions progress through these states:

• QUEUED - Session is waiting to start
• PLANNING - Jules is creating a plan
• AWAITING_PLAN_APPROVAL - Waiting for user to approve the plan
• AWAITING_USER_FEEDBACK - Waiting for user input
• IN_PROGRESS - Jules is working on the task
• PAUSED - Session is paused
• FAILED - Session failed
• COMPLETED - Session completed successfully

Example Workflow

1. List available repositories:

   Use the list_sources tool to see which repos are available
   

2. Create a coding task:

   Use create_session with:
   - prompt: "Add a dark mode toggle to the settings page"
   - source: "sources/github/myorg/myrepo"
   

3. Monitor progress:

   Use get_session to check the session state
   Use list_activities to see what Jules is doing
   

4. Interact with Jules:

   Use send_message if Jules needs clarification
   Use approve_plan if plan approval is required
   

5. Get the result:

   Once session is COMPLETED, check the outputs field for PR URL
   

API Reference

This server wraps the Google Jules API (v1alpha).

License

MIT