# Jules MCP

A small MCP server for the official **Google Jules REST API**.

It lets an MCP client (ChatGPT-compatible MCP host, Claude, Cursor, an agent harness, etc.) create and inspect Jules coding sessions without exposing the Jules API key to the model.

The server targets the current Jules `v1alpha` API and the current MCP Python SDK v2.

## What it exposes

Tools:

- `jules_list_sources` — list GitHub repositories connected to Jules.
- `jules_get_source` — inspect one source and its branches.
- `jules_list_sessions` — list Jules sessions.
- `jules_get_session` — get current state and outputs for a session.
- `jules_create_session` — start a coding task in a connected repository.
- `jules_send_message` — send follow-up instructions to an **active** session.
- `jules_approve_plan` — approve a plan when plan approval was requested.
- `jules_list_activities` — read immutable session events and artifacts.
- `jules_get_activity` — fetch one activity.
- `jules_session_snapshot` — get session + latest activities in one MCP call.
- `jules_wait_for_session` — bounded polling until the session needs input or finishes.

Destructive session deletion is intentionally not exposed in v0.1.0.

## Requirements

- Python 3.10+
- A Google Jules account with API access
- A Jules API key
- Jules GitHub App installed for repositories you want Jules to work on

Create/copy the API key in Jules settings and keep it secret. The official API authenticates with the `x-goog-api-key` header.

## Install

With `uv`:

```bash
git clone https://github.com/Toligrim/Jules-MCP.git
cd Jules-MCP
uv sync
```

Or with pip:

```bash
pip install -e .
```

Set the API key in the environment of the MCP server process:

```bash
export JULES_API_KEY='your-key-here'
```

Do **not** put a real key in this repository, MCP configuration committed to Git, screenshots, logs, or prompts.

## Run over stdio

Stdio is the default and is best for a local MCP host:

```bash
uv run jules-mcp
```

Equivalent:

```bash
uv run jules-mcp --transport stdio
```

Example MCP host configuration:

```json
{
  "mcpServers": {
    "jules": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/Jules-MCP", "run", "jules-mcp"],
      "env": {
        "JULES_API_KEY": "${JULES_API_KEY}"
      }
    }
  }
}
```

Whether `${JULES_API_KEY}` expansion is supported depends on the MCP host. Prefer setting the secret in the service/process environment rather than writing it into a config file.

## Run over Streamable HTTP

For a local or server deployment:

```bash
uv run jules-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

The MCP endpoint is:

```text
http://127.0.0.1:8000/mcp
```

Environment equivalents:

- `JULES_MCP_TRANSPORT=streamable-http`
- `JULES_MCP_HOST=127.0.0.1`
- `JULES_MCP_PORT=8000`
- `JULES_MCP_PATH=/mcp`

### Security warning for remote deployment

This project deliberately binds Streamable HTTP to `127.0.0.1` by default. Do **not** expose the raw endpoint directly to the public Internet.

If you place it behind Cloudflare Tunnel, a reverse proxy, or another gateway, add authentication/access control at that layer. The Jules API key remains server-side, but an unauthenticated public MCP endpoint could otherwise let strangers operate your Jules account.

## Typical workflow

1. Call `jules_list_sources` and choose the repository source.
2. Call `jules_create_session` with a prompt and optionally a starting branch.
3. Use `jules_get_session`, `jules_list_activities`, `jules_session_snapshot`, or `jules_wait_for_session` to monitor work.
4. If the session returns `AWAITING_PLAN_APPROVAL`, call `jules_approve_plan`.
5. If it returns `AWAITING_USER_FEEDBACK`, call `jules_send_message` with the requested clarification.
6. Read session outputs for the generated change set / pull request.

Important: the official Jules API documents `sendMessage` for an **active session**. A `COMPLETED` session may reject follow-up messages; this MCP server returns the Jules HTTP/API error instead of hiding it.

## Example tool inputs

Create a task:

```json
{
  "prompt": "Add regression tests for the parser and open a PR. Do not merge it.",
  "source": "sources/github/Toligrim/SomeRepo",
  "starting_branch": "main",
  "title": "Parser regression tests",
  "require_plan_approval": false
}
```

Inspect activities incrementally:

```json
{
  "session_id": "123456789",
  "page_size": 100,
  "create_time": "2026-09-19T12:00:00Z"
}
```

## Error behavior

Jules REST errors are returned to MCP callers in a structured form:

```json
{
  "ok": false,
  "error": {
    "message": "...",
    "status_code": 400,
    "status": "FAILED_PRECONDITION",
    "payload": {}
  }
}
```

This is useful for cases such as trying to send a follow-up message to a session that is no longer active.

## Development

Run client unit tests:

```bash
uv run --extra test pytest
```

The tests use `httpx.MockTransport`; they do not call the real Jules API and do not require a real API key.

## API references

- Jules REST API quickstart: https://jules.google/docs/api/reference/
- Authentication: https://jules.google/docs/api/reference/authentication/
- Sessions: https://jules.google/docs/api/reference/sessions
- Activities: https://jules.google/docs/api/reference/activities/
- Sources: https://jules.google/docs/api/reference/sources/
- MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

## License

MIT