# Jules MCP Server
MCP server that exposes Google Jules capabilities using **@google/jules-sdk**. This unified implementation uses the SDK plus direct API calls where needed, while keeping SDK-backed caching, snapshots, and artifact handling. MCP tools may use either the SDK or the REST API, whichever is the best fit for the specific operation.
## Setup
1. Install dependencies
2. Provide `JULES_API_KEY` via environment or `~/.jules/config.json`
3. Build the server
```bash
npm install
npm run build
```
Run locally:
```bash
JULES_API_KEY=your_api_key node dist/cli.js
```
## OpenCode Integration
This repo includes a project-level OpenCode config at `.opencode/opencode.json`. For global setup, add to `~/.config/opencode/opencode.json` (update the command path to where you built this server):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jules": {
"type": "local",
"command": ["node", "/path/to/your/jules-mcp/dist/cli.js"],
"environment": {
"JULES_API_KEY": "your_api_key"
}
}
}
}
```
## Antigravity Integration
Example OpenCode plugin enablement snippet (merge into your config):
```json
{
"$schema": "https://opencode.ai/config.json",
"plugins": {
"opencode-antigravity-auth": {
"enabled": true
}
}
}
```
## Tools
### SDK Tools
| Tool | Purpose | Key Params | Returns |
| --- | --- | --- | --- |
| `create_session` | Create a new Jules session or automated run (supports repoless sessions). | `prompt` (req)<br>`repo`<br>`branch`<br>`interactive`<br>`autoPr` | `Session created. ID: <sessionId>` |
| `list_sessions` | List recent sessions with pagination. | `pageSize`<br>`pageToken` | `{ sessions: [...], nextPageToken? }` |
| `get_session_state` | Session dashboard (status, last activity/message, pending plan). | `sessionId` (req) | Status object with activity/message/plan context |
| `send_reply_to_session` | Approve plan, send a message, or ask and wait for a reply. | `sessionId` (req)<br>`action` (approve/send/ask)<br>`message` (send/ask) | Confirmation or agent reply |
| `get_code_review_context` | Summarize code changes with file list and metadata. | `sessionId` (req)<br>`activityId`<br>`format`<br>`filter`<br>`detail` | Formatted summary string |
| `show_code_diff` | Get the unified diff for a session or file. | `sessionId` (req)<br>`file`<br>`activityId` | Unified diff text |
| `query_cache` | Query the local cache using JQL. | `query` (req) | `{ results: [...], _meta? }` |
Query example:
```json
{
"query": {
"from": "sessions",
"where": { "state": "failed" },
"limit": 5
}
}
```
### Additional Tools (`jules_*`)
These tools are part of the same unified server and expose REST-style workflows plus convenience operations. They may use the SDK or the REST API under the hood, depending on which path is required for the operation. They return a structured `ToolResult` object:
```
{ success, message, data?, error?, suggestedNextSteps? }
```
| Tool | Purpose | Key Params | Notes |
| --- | --- | --- | --- |
| `jules_list_sources` | List connected repositories. | `pageSize`<br>`pageToken` | Returns `{ sources, hasMore, nextPageToken }` |
| `jules_get_source` | Get details for a connected repository. | `source` (req) | Accepts `sources/github/owner/repo` or `owner/repo` |
| `jules_create_session` | Create a session with automation settings. | `prompt` (req)<br>`repo` (req)<br>`branch`<br>`title`<br>`automationMode`<br>`requirePlanApproval` | Draft PR falls back to `AUTO_CREATE_PR` if not supported |
| `jules_get_session` | Get session status/details. | `sessionId` (req) | — |
| `jules_list_sessions` | List sessions with pagination. | `pageSize`<br>`pageToken` | — |
| `jules_approve_plan` | Approve a pending plan. | `sessionId` (req) | — |
| `jules_reject_plan` | Reject a plan with feedback. | `sessionId` (req)<br>`feedback` | Uses REST endpoint |
| `jules_send_message` | Send a message to a session. | `sessionId` (req)<br>`message` (req) | — |
| `jules_cancel_session` | Cancel a running session. | `sessionId` (req) | Uses REST endpoint |
| `jules_list_activities` | List activities in a session. | `sessionId` (req)<br>`pageSize`<br>`pageToken` | — |
| `jules_get_latest_activity` | Get most recent activity. | `sessionId` (req) | — |
| `jules_get_session_plan` | Get latest plan (if generated). | `sessionId` (req) | Plan rejection detection uses REST activity listing |
| `jules_wait_for_completion` | Wait for completion or timeout. | `sessionId` (req)<br>`timeoutMs`<br>`pollIntervalMs` | — |
| `jules_wait_for_plan` | Wait for plan generation. | `sessionId` (req)<br>`timeoutMs` | — |
| `jules_create_and_wait` | Create and optionally wait for completion. | `prompt` (req)<br>`repo` (req)<br>`branch`<br>`title`<br>`automationMode`<br>`waitForCompletion`<br>`timeoutMs`<br>`requirePlanApproval` | Draft PR falls back to `AUTO_CREATE_PR` if not supported |
| `jules_quick_task` | Create session with defaults and wait. | `prompt` (req)<br>`repo` (req)<br>`branch`<br>`createPr` | — |
| `jules_get_session_summary` | Combined session + activity summary. | `sessionId` (req) | — |
| `jules_sync_local_codebase` | Apply Jules diff to a local git repo. | `sessionId` (req)<br>`repoPath`<br>`activityId`<br>`file`<br>`dryRun`<br>`allowDirty`<br>`autoStash`<br>`threeWay` | Refuses dirty trees by default unless `allowDirty=true` or `autoStash=true` |
### Hidden Tool (Not Listed in MCP)
| Tool | Purpose | Key Params | Notes |
| --- | --- | --- | --- |
| `get_bash_outputs` | Get bash command outputs from a session. | `sessionId` (req)<br>`activityIds` | Not listed in MCP discovery |
## Behavior Notes
- `AUTO_CREATE_DRAFT_PR` is not supported by the SDK. When requested for `jules_create_session` or `jules_create_and_wait`, the server retries with `AUTO_CREATE_PR`.
- `jules_reject_plan` and `jules_cancel_session` use direct REST endpoints when the SDK does not expose public helpers.
- Plan rejection status depends on a `planRejected` activity; if the API does not emit it, the status remains `pending_approval`.
- `jules_sync_local_codebase` applies patches via `git apply` and refuses dirty working trees unless `allowDirty=true` or `autoStash=true`.
## Configuration
The server reads configuration from:
- `JULES_API_KEY` env var **or** `~/.jules/config.json`
- Optional overrides:
- `JULES_API_BASE_URL`
- `JULES_API_TIMEOUT` or `JULES_REQUEST_TIMEOUT_MS`
- `JULES_POLL_INTERVAL`
- `JULES_RATE_LIMIT_MAX_RETRY_MS`
- `JULES_RATE_LIMIT_BASE_DELAY_MS`
- `JULES_RATE_LIMIT_MAX_DELAY_MS`
## CLI
The CLI supports `doctor` and `config` commands (like the official SDK MCP):
```bash
# Check environment and API connectivity
jules-mcp-server doctor
# Save API key to ~/.jules/config.json
jules-mcp-server config --key YOUR_KEY
```
## Credits
Special thanks to [David East](https://twitter.com/_davideast) for building the SDK and API on which this MCP is based.
