Jules MCP Server

Production-grade Model Context Protocol (MCP) server for Google Jules AI, built with FastMCP.

Provides an enterprise-ready bridge for AI Agents (Antigravity, Claude Desktop, Cursor, VS Code, Goose) to inspect, mentor, plan, and automate Google Jules execution sessions natively via HTTP, SSE, or Stdio transport.

---

Key Features

• ⚡ Sub-Second Response Times: Single-page fast listing (fetch_all=False by default) returning session data in <200ms.
• 🛡️ Hardened Network Resilience: Per-request isolated HTTP clients (httpx.AsyncClient) with strict timeouts (httpx.Timeout(8.0)) catching asyncio.CancelledError and TimeoutError to guarantee non-blocking agent turns.
• 🧹 Concurrent Automatic Session Cleanup: Parallel scanning and deletion of terminal/inactive sessions (COMPLETED, FINISHED, TERMINATED, CANCELLED, FAILED, EXPIRED, CLOSED) using asyncio.gather (clean_completed_sessions).
• 🔒 Type Sanitization: Primitive string and boolean defaults (title: "", starting_branch: "main", fetch_all: false) eliminating null validation errors in client schema parsers.
• 🔌 Multi-Transport Support: Native HTTP JSON-RPC (/mcp), Server-Sent Events (/sse), and Stdio bridge support.
• 🐳 Production Docker Image: Pre-compiled multi-arch image hosted on GitHub Container Registry (ghcr.io/cavuminfundo/jules-mcp-server:latest).

---

🛠️ MCP Tools Reference

Tool Name	Description	Default Parameters
list_sessions	List Jules sessions with fast single-page default or optional auto-pagination.	page_size: 50, page_token: "", fetch_all: false
get_session	Retrieve full details and current state for a specific session ID or name.	session_id: string
create_session	Launch a new Jules AI session for a target repository.	source: string, prompt: string, title: "", starting_branch: "main", require_plan_approval: false
list_activities	Fetch activity history and generated plans for a session.	session_id: string, page_size: 20, page_token: ""
list_all_activities	Fetch all activity history for a session using automatic pagination.	session_id: string
get_activity	Retrieve details for a specific activity ID within a session.	session_id: string, activity_id: string
approve_session_plan	Approve a pending session plan in a single native call.	session_id: string
send_session_message	Send mentoring feedback, answers, or directives to an active session.	session_id: string, message: string
delete_session	Permanently delete a completed or inactive session.	session_id: string
clean_completed_sessions	Concurrently scan and delete all terminal/inactive sessions.	None
list_sources	List accessible source GitHub repositories connected to Jules.	page_size: 50, page_token: "", filter_str: ""
get_all_sources	Retrieve all accessible source repositories with auto-pagination.	filter_str: ""

---

🚀 Quickstart & Container Deployment

1. Docker Compose (Recommended Production Setup)

Create a docker-compose.yml file:

services:
  jules-mcp:
    image: ghcr.io/cavuminfundo/jules-mcp-server:latest
    container_name: jules_mcp_server
    dns:
      - 8.8.8.8
      - 8.8.4.4
    environment:
      - JULES_API_KEY=your_google_jules_api_key_here
    ports:
      - "8000:8000"
    restart: unless-stopped

Run the container:

docker compose up -d

2. Standalone Docker Run

docker run -d \
  --name jules_mcp_server \
  -e JULES_API_KEY="your_google_jules_api_key_here" \
  -p 8000:8000 \
  --restart unless-stopped \
  ghcr.io/cavuminfundo/jules-mcp-server:latest

---

🔌 Client Integration Guide (mcp_config.json)

Add jules-mcp to your AI client configuration (Antigravity, Claude Desktop, Cursor, VS Code, Goose).

Option A: Stateless HTTP JSON-RPC Transport (Recommended - Zero Session State)

Stateless endpoint (/rpc) executing tool calls instantly without stateful SSE connection ID caching or reconnection timeouts:

{
  "mcpServers": {
    "jules-mcp": {
      "type": "http",
      "url": "http://<SERVER_IP_OR_HOST>:8000/rpc"
    }
  }
}

Option B: Native Stdio Transport Bridge (SSH / Docker)

Direct process stdio stream execution bypassing HTTP network sockets completely:

{
  "mcpServers": {
    "jules-mcp": {
      "command": "ssh",
      "args": [
        "-o",
        "StrictHostKeyChecking=no",
        "user@<SERVER_IP_OR_HOST>",
        "docker",
        "exec",
        "-i",
        "jules_mcp_server",
        "python3",
        "-m",
        "jules_mcp.jules_mcp",
        "stdio"
      ]
    }
  }
}

Option C: SSE Transport (Server-Sent Events)

Stateful stream connection for streaming clients:

{
  "mcpServers": {
    "jules-mcp": {
      "type": "sse",
      "url": "http://<SERVER_IP_OR_HOST>:8000/sse"
    }
  }
}

Stdio Transport Bridge (mcp-remote)

{
  "mcpServers": {
    "jules-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://<SERVER_IP_OR_HOST>:8000/sse",
        "--allow-http"
      ]
    }
  }
}

---

🛠️ Local Development & Testing

# Clone the repo
git clone https://github.com/cavuminfundo/jules-mcp-server.git
cd jules-mcp-server

# Set environment API key
export JULES_API_KEY="your_google_jules_api_key"

# Install dependencies and start server with uv
uv sync
uv run python -m jules_mcp.jules_mcp

---

📄 License

Distributed under the MIT License. See LICENSE for more information.