# 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](https://jules.google.com/settings))
- GitHub repositories installed in Jules
## Installation
### Using uv (Recommended)
```bash
# Clone the repository
git clone https://github.com/yourusername/jules-mcp.git
cd jules-mcp
# Install dependencies with uv
uv sync
```
### Using pip
```bash
# 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:
```bash
export JULES_API_KEY="your-api-key-here"
```
## Usage
### Running Standalone
```bash
# 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`:
```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)
```json
{
"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)](https://developers.google.com/jules/api/reference/rest).
## License
MIT
