google-jules-mcp-server

If you're searching for a way to drive Google's Jules coding agent from Claude, Cursor, VS Code Copilot, or any other MCP client, this is that bridge. google-jules-mcp-server is an unofficial Model Context Protocol server that exposes the full Jules API (v1alpha) as 13 tools, so your assistant can create sessions, poll status, approve plans, and fetch the resulting pull request without you leaving the chat.

Developers running Jules across many repositories at once use it to let their AI assistant manage the whole async workflow: kick off a task, check on it later, and hand back a PR link when it's done, instead of switching to the Jules web app to babysit progress. Every response is validated at runtime through Zod schemas, so a drifted Jules API response fails loudly rather than silently breaking downstream code.

Model Context Protocol (MCP) server for Google's Jules AI coding agent — unofficial. Lets AI assistants like Claude create and manage asynchronous coding tasks through the Jules API v1alpha.

Overview

Jules is Google's AI coding agent that executes development tasks in isolated cloud VMs — generating code, fixing bugs, writing tests, updating dependencies, and refactoring across files. This server exposes the full Jules API surface as 13 MCP tools, covering repository sources, session lifecycle, and activity logs.

Tasks run asynchronously and typically complete in 5–60 minutes depending on complexity.

Architecture

The server is organized by Jules resource domain rather than as one flat file:

src/
├── index.ts                 # entrypoint: connects the stdio transport
├── server.ts                 # createServer(): wires the MCP server + all tool registrations
├── core/                     # transport-agnostic: auth, HTTP client, retry/backoff, typed errors, logging
└── resources/
    ├── sources/               # jules_list_sources, jules_get_source
    ├── sessions/              # session lifecycle (create/list/status/message/approve/output/delete/archive/unarchive)
    └── activities/            # jules_list_activities, jules_get_activity

Each resource module owns its own Zod schemas, a typed API client, and its MCP tool registrations. Zod schemas are the single source of truth: TypeScript types are inferred from them (z.infer), and every Jules API response is validated at runtime through core/http-client.ts — so a drifted API response fails loudly as a JulesResponseValidationError instead of silently producing undefineds downstream.

core/http-client.ts also centralizes retry-with-backoff (bounded, honors Retry-After) and a typed error hierarchy (JulesAuthError, JulesNotFoundError, JulesRateLimitError, JulesServerError, JulesClientError, JulesNetworkError, JulesResponseValidationError) so callers can distinguish failure modes programmatically rather than pattern-matching error strings.

Prerequisites

1. Google Account with Jules access
2. Jules API Key — get one from https://jules.google.com/settings#api (up to 3 keys allowed)
3. GitHub Integration — install the Jules GitHub app at https://jules.google.com to connect repositories
4. Node.js 22+

Quick Start

1. Install

The package is published on npm as google-jules-mcp-server. Most MCP clients can run it directly via npx — no separate install step needed, skip to step 2.

If you'd rather install it once instead of letting your client invoke npx on every launch:

npm install -g google-jules-mcp-server

This puts a google-jules-mcp binary on your PATH.

Building from source (for contributors, or to run unreleased changes):

git clone https://github.com/georgeracu/google-jules-mcp-server.git
cd google-jules-mcp-server
npm install
npm run build

2. Configure your API key

Get a key from https://jules.google.com/settings#api. Set it directly in your MCP client's server config (see below) — that's the only place it needs to live for normal use.

If you're building from source and want to run npm run test:smoke or use .env for local scripts:

cp .env.example .env
# edit .env and set JULES_API_KEY

3. Register the server with your MCP client

Claude Desktop — edit the config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "jules": {
      "command": "npx",
      "args": ["-y", "google-jules-mcp-server"],
      "env": { "JULES_API_KEY": "your_actual_jules_api_key_here" }
    }
  }
}

Claude Code:

claude mcp add jules -s user -e JULES_API_KEY=your_actual_jules_api_key_here -- npx -y google-jules-mcp-server

GitHub Copilot CLI:

copilot mcp add jules -e JULES_API_KEY=your_actual_jules_api_key_here -- npx -y google-jules-mcp-server

Or edit ~/.copilot/mcp-config.json directly:

{
  "mcpServers": {
    "jules": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "google-jules-mcp-server"],
      "env": { "JULES_API_KEY": "your_actual_jules_api_key_here" },
      "tools": ["*"]
    }
  }
}

VS Code (Copilot Chat agent mode) — via terminal:

code --add-mcp '{"name":"jules","command":"npx","args":["-y","google-jules-mcp-server"],"env":{"JULES_API_KEY":"your_actual_jules_api_key_here"}}'

Or add to .vscode/mcp.json (workspace) or via MCP: Open User Configuration (user-level):

{
  "servers": {
    "jules": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "google-jules-mcp-server"],
      "env": { "JULES_API_KEY": "your_actual_jules_api_key_here" }
    }
  }
}

Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "jules": {
      "command": "npx",
      "args": ["-y", "google-jules-mcp-server"],
      "env": { "JULES_API_KEY": "your_actual_jules_api_key_here" }
    }
  }
}

OpenAI Codex CLI:

codex mcp add jules --env JULES_API_KEY=your_actual_jules_api_key_here -- npx -y google-jules-mcp-server

Or edit ~/.codex/config.toml directly:

[mcp_servers.jules]
command = "npx"
args = ["-y", "google-jules-mcp-server"]
env = { JULES_API_KEY = "your_actual_jules_api_key_here" }

If you installed globally instead, replace "command": "npx", "args": ["-y", "google-jules-mcp-server"] with "command": "google-jules-mcp", "args": [] (and any npx -y google-jules-mcp-server in a CLI command above with just google-jules-mcp).

If you're running from a local clone instead, use "command": "node", "args": ["/absolute/path/to/google-jules-mcp-server/build/index.js"] (an absolute path to build/index.js).

Behind a corporate proxy — to support enterprise/corporate proxy setups without requiring any server-side config, the server automatically picks up proxy settings from the environment. The underlying EnvHttpProxyAgent (from undici) honours the standard HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy, and NO_PROXY variables. What catches people out is that your MCP client spawns the server as a child process, so a variable exported in ~/.zshrc never reaches a GUI-launched app. Set it in the same env block as your API key:

{
  "mcpServers": {
    "jules": {
      "command": "npx",
      "args": ["-y", "google-jules-mcp-server"],
      "env": {
        "JULES_API_KEY": "your_actual_jules_api_key_here",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Proxied requests are broken in 0.2.3 and earlier, where every call fails on a gzipped response the client never decoded. If you hit that, upgrade rather than reconfigure.

Restart your client after editing its config.

4. Verify

Ask your assistant: "List my Jules repositories." You should see the jules server connected with 16 tools available.

Available Tools