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

List available repositories:

Use the list_sources tool to see which repos are available

Create a coding task:

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

Monitor progress:

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

Interact with Jules:

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

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

Jules MCP Server

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

List available repositories:

Use the list_sources tool to see which repos are available

Create a coding task:

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

Monitor progress:

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

Interact with Jules:

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

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