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

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.