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

Related MCP server: MCP HTTP Proxy

🛠️ MCP Tools Reference

🚀 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.