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

Install dependencies
Provide JULES_API_KEY via environment or ~/.jules/config.json
Build the server

npm install
npm run build

Run locally:

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):

{
  "$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):

{
  "$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) `repo` `branch` `interactive` `autoPr`	`Session created. ID: <sessionId>`
`list_sessions`	List recent sessions with pagination.	`pageSize` `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) `action` (approve/send/ask) `message` (send/ask)	Confirmation or agent reply
`get_code_review_context`	Summarize code changes with file list and metadata.	`sessionId` (req) `activityId` `format` `filter` `detail`	Formatted summary string
`show_code_diff`	Get the unified diff for a session or file.	`sessionId` (req) `file` `activityId`	Unified diff text
`query_cache`	Query the local cache using JQL.	`query` (req)	`{ results: [...], _meta? }`

Query example:

{
  "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` `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) `repo` (req) `branch` `title` `automationMode` `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` `pageToken`	—
`jules_approve_plan`	Approve a pending plan.	`sessionId` (req)	—
`jules_reject_plan`	Reject a plan with feedback.	`sessionId` (req) `feedback`	Uses REST endpoint
`jules_send_message`	Send a message to a session.	`sessionId` (req) `message` (req)	—
`jules_cancel_session`	Cancel a running session.	`sessionId` (req)	Uses REST endpoint
`jules_list_activities`	List activities in a session.	`sessionId` (req) `pageSize` `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) `timeoutMs` `pollIntervalMs`	—
`jules_wait_for_plan`	Wait for plan generation.	`sessionId` (req) `timeoutMs`	—
`jules_create_and_wait`	Create and optionally wait for completion.	`prompt` (req) `repo` (req) `branch` `title` `automationMode` `waitForCompletion` `timeoutMs` `requirePlanApproval`	Draft PR falls back to `AUTO_CREATE_PR` if not supported
`jules_quick_task`	Create session with defaults and wait.	`prompt` (req) `repo` (req) `branch` `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) `repoPath` `activityId` `file` `dryRun` `allowDirty` `autoStash` `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) `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):

# 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 for building the SDK and API on which this MCP is based.

Jules MCP Server

Jules MCP Server

Setup

OpenCode Integration

Antigravity Integration

Tools

SDK Tools

Additional Tools (jules_*)

Hidden Tool (Not Listed in MCP)

Behavior Notes

Configuration

CLI

Credits

Reviews

Additional Tools (`jules_*`)