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