jules-mcp-server by jarossk - MCP Server

Jules MCP Server (Node.js)

A Model Context Protocol (MCP) server that exposes the Google Jules API so coding agents such as Claude Code, OpenAI Codex, GitHub Copilot and Cursor can create and manage Jules sessions programmatically.

Requirements

Node.js 20+
A Jules API key with access to the v1alpha endpoints
(Optional) Access to one of the supported IDE agents (Claude Code, Codex CLI, GitHub Copilot, Cursor)

Installation

npm install

Environment

Variable	Required	Default	Description
`JULES_API_KEY`	✅	–	API key used for authenticating calls to `https://jules.googleapis.com`.
`JULES_API_BASE_URL`	❌	`https://jules.googleapis.com`	Override if you need to point at a proxy or mock Jules deployment.

Create a .env file or inject the values through your client configuration (see below).

Running with the MCP Inspector

The inspector is the quickest way to verify connectivity before wiring up an IDE:

JULES_API_KEY="your-api-key" npm run inspector

This launches the interactive UI at http://localhost:6274/ where you can exercise each MCP tool and inspect responses.

Tools exposed by the server

Tool	HTTP call	Description
`jules_create_session`	`POST /v1alpha/sessions`	Create a new session bound to a source (supports optional title, plan approval, starting branch).
`jules_get_session`	`GET /v1alpha/{name}`	Fetch a single session by resource name (e.g. `sessions/123`).
`jules_list_sessions`	`GET /v1alpha/sessions`	List sessions with pagination controls.
`jules_approve_plan`	`POST /v1alpha/{session}:approvePlan`	Approve the outstanding plan so the agent can proceed.
`jules_send_message`	`POST /v1alpha/{session}:sendMessage`	Send a user message into a running session.
`jules_list_activities`	`GET /v1alpha/{parent}/activities`	Enumerate activities (plans, updates, artifacts) for a session.
`jules_get_activity`	`GET /v1alpha/{name}`	Retrieve an individual activity by resource name.
`jules_list_sources`	`GET /v1alpha/sources`	Discover available Jules sources (supports filter, pagination).
`jules_get_source`	`GET /v1alpha/{name}`	Read a single source definition.

All tools return either JSON payloads (application/json) or short status messages so agents can chain further calls.

Example workflow

Use jules_list_sources to find the repository or project you want to work with.
Call jules_create_session with the source name (e.g. sources/octo-app) and the starting prompt.
If the session requires manual sign-off, run jules_approve_plan after reviewing the plan in the Jules UI.
Keep the discussion going via jules_send_message and poll jules_list_activities to stream progress, code patches, artifacts, and completion events.

Client integration

The repository ships with a reusable MCP configuration template at . Copy the mcpServers.jules entry into the configuration file used by your client of choice and replace the placeholder path/API key.

Claude Desktop (Claude Code)

Open or create ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%/Claude/claude_desktop_config.json (Windows).
Add the jules entry under the top-level "mcpServers" object:

"mcpServers": {
  "jules": {
    "command": "node",
    "args": ["/full/path/to/mcp-server-node/mcp-server.js"],
    "env": {
      "JULES_API_KEY": "replace-with-your-api-key"
    }
  }
}

Restart Claude Desktop and enable Claude Code. The new tools will appear in the tool list.

Claude Code CLI

Claude Code’s CLI can register MCP servers directly. The CLI stores configuration per scope (local, project, or user); use the user scope if you want the Jules server available everywhere.

Add the server (replace the path/API key):

claude mcp add jules \
  --scope user \
  --env JULES_API_KEY=your-api-key \
  --env JULES_API_BASE_URL=https://jules.googleapis.com \
  -- node /full/path/to/mcp-server-node/mcp-server.js

Confirm the registration:

claude mcp list

Launch claude and the CLI will surface the jules_* tools for use inside Claude Code sessions.

See Anthropic’s guide for more CLI options, scopes, and JSON-based configuration: Connect Claude Code to tools via MCP.

OpenAI Codex CLI

Update ~/.config/openai-codex/mcp.json (Linux/macOS) or %AppData%/OpenAI Codex/mcp.json (Windows).
Merge the same "jules" definition into the mcpServers map.
Restart the Codex CLI (codex reload) to pick up the server.

GitHub Copilot (VS Code / JetBrains / Neovim)

Edit the Copilot MCP config: ~/.config/github-copilot/mcp.json on Linux, ~/Library/Application Support/GitHub Copilot/mcp.json on macOS, or %AppData%\GitHub Copilot\mcp.json on Windows.
Insert the jules server entry under mcpServers and add JULES_API_KEY.
Reload your IDE. Copilot Chat should list the Jules tools automatically.

Cursor

Cursor also supports the same configuration format via ~/.cursor/mcp.json. Copy the jules block into the mcpServers section and restart Cursor.

💡 All clients accept optional environment overrides. If you need to point at a proxy Jules endpoint, add "JULES_API_BASE_URL": "https://your-proxy.example.com" to the env section.

Development notes

The server is written in plain JavaScript (ESM) and uses the official @modelcontextprotocol/sdk plus fetch for HTTP.
Jules API errors are surfaced with descriptive messages so agents receive actionable feedback.
Extend the toolset by following the existing pattern: define a Zod schema, call client.request, and return structured MCP content.

jarossk/jules-mcp-server