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_KEYvia 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)repobranchinteractiveautoPr |
Session created. ID: <sessionId> |
list_sessions |
List recent sessions with pagination. | pageSizepageToken |
{ 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)activityIdformatfilterdetail |
Formatted summary string |
show_code_diff |
Get the unified diff for a session or file. | sessionId (req)fileactivityId |
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. | pageSizepageToken |
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)branchtitleautomationModerequirePlanApproval |
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. | pageSizepageToken |
— |
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)pageSizepageToken |
— |
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)timeoutMspollIntervalMs |
— |
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)branchtitleautomationModewaitForCompletiontimeoutMsrequirePlanApproval |
Draft PR falls back to AUTO_CREATE_PR if not supported |
jules_quick_task |
Create session with defaults and wait. | prompt (req)repo (req)branchcreatePr |
— |
jules_get_session_summary |
Combined session + activity summary. | sessionId (req) |
— |
jules_sync_local_codebase |
Apply Jules diff to a local git repo. | sessionId (req)repoPathactivityIdfiledryRunallowDirtyautoStashthreeWay |
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_PRis not supported by the SDK. When requested forjules_create_sessionorjules_create_and_wait, the server retries withAUTO_CREATE_PR.jules_reject_planandjules_cancel_sessionuse direct REST endpoints when the SDK does not expose public helpers.- Plan rejection status depends on a
planRejectedactivity; if the API does not emit it, the status remainspending_approval. jules_sync_local_codebaseapplies patches viagit applyand refuses dirty working trees unlessallowDirty=trueorautoStash=true.
Configuration
The server reads configuration from:
JULES_API_KEYenv var or~/.jules/config.json- Optional overrides:
JULES_API_BASE_URLJULES_API_TIMEOUTorJULES_REQUEST_TIMEOUT_MSJULES_POLL_INTERVALJULES_RATE_LIMIT_MAX_RETRY_MSJULES_RATE_LIMIT_BASE_DELAY_MSJULES_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.
