google-jules-mcp-server

google-jules-mcp-server

如果你正在寻找一种方式，让 Claude、Cursor、VS Code Copilot 或任何其他 MCP 客户端驱动 Google 的 Jules 编码 Agent，这就是连接桥。google-jules-mcp-server 是一个非官方的 Model Context Protocol 服务，可将完整的 Jules API（v1alpha）作为 13 个工具开放，让你的助手无需离开聊天界面，就能创建会话、轮询状态、批准计划并获取生成的拉取请求。

同时在多个代码仓库中运行 Jules 的开发者可以借助它，让 AI 助手管理整个异步工作流：启动任务、之后查看进度，并在任务完成时返回 PR 链接，而不必切换到 Jules 网页应用来盯着进度。每个响应都会在运行时通过 Zod 架构进行验证，因此 Jules API 响应发生偏差时会明确报错，而不会悄然破坏下游代码。

这是一个用于 Google Jules AI 编码 Agent 的 Model Context Protocol（MCP）服务，非官方版本。它让 Claude 等 AI 助手能够通过 Jules API v1alpha 创建和管理异步编码任务。

概述

Jules 是 Google 的 AI 编码 Agent，可在隔离的云 VM 中执行开发任务，包括生成代码、修复 bug、编写测试、更新依赖项以及跨文件重构。此服务将完整的 Jules API 功能作为 13 个 MCP 工具开放，涵盖代码仓库源、会话生命周期和活动日志。

任务以异步方式运行，通常需要 5–60 分钟完成，具体取决于复杂程度。

架构

此服务按照 Jules 资源领域组织，而不是将所有内容放在一个扁平文件中：

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

每个资源模块都包含自己的 Zod 架构、类型化 API 客户端和 MCP 工具注册。Zod 架构是唯一可信来源：TypeScript 类型由其推导得出（z.infer），而每个 Jules API 响应都会在运行时通过 core/http-client.ts 进行验证。因此，API 响应发生偏差时，会明确抛出 JulesResponseValidationError，而不会悄然导致下游出现 undefined。

core/http-client.ts 还集中处理带退避的重试（有上限，并遵循 Retry-After）和类型化错误层级（JulesAuthError、JulesNotFoundError、JulesRateLimitError、JulesServerError、JulesClientError、JulesNetworkError、JulesResponseValidationError），因此调用方可以通过编程方式区分故障类型，而不是对错误字符串进行模式匹配。

前提条件

1. Google 账号，并拥有 Jules 使用权限
2. Jules API 密钥 — 前往 https://jules.google.com/settings#api 获取（最多允许 3 个密钥）
3. GitHub 集成 — 在 https://jules.google.com 安装 Jules GitHub 应用以连接代码仓库
4. Node.js 22+

快速开始

1. 安装

该软件包已发布到 npm，名称为 google-jules-mcp-server。大多数 MCP 客户端都可以通过 npx 直接运行它——无需单独安装，直接跳到第 2 步即可。

如果你更愿意一次性安装，而不是每次启动时都让客户端调用 npx：

npm install -g google-jules-mcp-server

这会将一个 google-jules-mcp 可执行文件放入你的 PATH。

从源代码构建（适用于贡献者，或运行尚未发布的更改）：

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

2. 配置 API 密钥

从 https://jules.google.com/settings#api 获取密钥。将它直接设置在 MCP 客户端的服务配置中（见下文）——正常使用时只需在这里保存密钥。

如果你从源代码构建，并希望运行 npm run test:smoke 或使用 .env 执行本地脚本：

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

3. 在 MCP 客户端中注册服务

Claude Desktop——编辑配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "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

或者直接编辑 ~/.copilot/mcp-config.json：

{
  "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 模式）——通过终端：

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

或者添加到 .vscode/mcp.json（工作区），或通过 MCP: Open User Configuration（用户级）添加：

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

Cursor——添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（仅限项目）：

{
  "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

或者直接编辑 ~/.codex/config.toml：

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

如果你采用全局安装，请将 "command": "npx", "args": ["-y", "google-jules-mcp-server"] 替换为 "command": "google-jules-mcp", "args": []（并将上文 CLI 命令中的所有 npx -y google-jules-mcp-server 替换为 google-jules-mcp）。

如果你从本地克隆运行，请使用 "command": "node", "args": ["/absolute/path/to/google-jules-mcp-server/build/index.js"]（将路径替换为 build/index.js 的绝对路径）。

使用企业代理——为支持企业代理配置而无需任何服务端配置，服务会自动读取环境中的代理设置。底层的 EnvHttpProxyAgent（来自 undici）遵循标准的 HTTPS_PROXY、https_proxy、HTTP_PROXY、http_proxy 和 NO_PROXY 变量。容易忽略的一点是，MCP 客户端会将服务作为子进程启动，因此，在 ~/.zshrc 中导出的变量无法传递给通过 GUI 启动的应用。请将其与 API 密钥一起设置在同一个 env 块中：

{
  "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"
      }
    }
  }
}

在 0.2.3 及更早版本中，通过代理发送的请求无法正常工作，因为客户端无法解码 gzip 压缩的响应，导致每次调用都失败。如果遇到这种情况，请升级，而不是重新配置。

编辑配置后，重启客户端。

4. 验证

向助手询问：“列出我的 Jules 代码库。”你应该会看到已连接的 jules 服务，并显示有 16 个工具可用。

可用工具

工具	用途
jules_list_sources	列出已连接到 Jules 的 GitHub 仓库
jules_get_source	获取一个已连接仓库的详细信息（分支、可见性）
jules_create_session	启动新的异步编码任务
jules_list_sessions	列出会话及其状态
jules_list_stuck_sessions	列出等待计划审批或用户反馈的会话，并自动处理分页
jules_get_status	检查会话状态和最近的活动
jules_send_message	向运行中的会话发送后续指令
jules_approve_plan	批准会话的执行计划（设置了 requirePlanApproval 时）
jules_get_session_output	获取已完成会话的最终输出（PR 详情）
jules_delete_session	永久删除会话
jules_archive_session	归档会话，但不删除
jules_unarchive_session	恢复已归档的会话
jules_wait_for_session	等待/轮询会话，直到其达到终止状态
jules_execute_and_wait	在一次调用中创建会话并等待其完成
jules_list_activities	获取会话的详细活动日志
jules_get_activity	按 ID 获取单项活动

输出大小与分页

这些工具返回的所有内容都会进入助手的上下文窗口，而自主编码会话可能会生成很长的 Agent 消息、进度说明和数百步的计划。因此，服务会限制返回内容的大小，并在截断内容时随响应明确说明，以便助手决定是否获取剩余内容。

工具	上限
jules_get_status	最近活动摘要中每条活动 100 个字符
jules_list_activities	每条约 800 个字符，每页约 10,000 个字符
jules_get_activity	8,000 个字符

jules_list_activities 中被截断的条目会列出重新请求该条目所需的 sessionId 和 activityId，你可以通过 jules_get_activity 获取；它会在大得多的单条活动额度下呈现相同活动——空间是原来的十倍，但仍然有限。8,000 个字符就是上限：单条活动没有续传令牌或偏移量，因此，jules_get_activity 响应若报告省略了字符，会明确说明，而不会指向其他位置。再次请求也会返回相同的截断内容。

如果为了满足页面额度而必须舍弃整条条目，响应末尾会显示 Showing 12 of 40 activities；此时应使用更小的 limit，而不是页面令牌，因为令牌会从整个请求页面之后继续，跳过你尚未看到的条目。

分页本身不受这些限制影响。jules_list_sources、jules_list_sessions 和 jules_list_activities 均接受 pageSize（或 limit）和 pageToken，并会在存在更多结果时返回 API 的 nextPageToken。

异步工作流模式

1. 创建会话——立即返回会话 ID。
2. 每隔 10–30 秒使用 jules_get_status 轮询。
3. 使用 jules_list_activities 监控详细进度。
4. 状态变为 COMPLETED 后，通过 jules_get_session_output 获取拉取请求 URL。

当你要求监控任务时，助手会自动处理此轮询循环。

会话监视器（卡住的会话）

如果你不希望 LLM 客户端为卡住的会话（例如 AWAITING_PLAN_APPROVAL 或 AWAITING_USER_FEEDBACK）持续轮询并消耗令牌，可以运行独立的会话监视器。它独立于任何 MCP 客户端运行，并会在会话卡住时向 Webhook 发送 JSON 负载。

必需的环境变量：

• JULES_API_KEY：你的 Jules API 密钥。
• JULES_WATCH_WEBHOOK_URL：用于接收 JSON 负载的 POST URL。

可选的环境变量：

• JULES_WATCH_INTERVAL_SECONDS：轮询间隔（秒），默认值为 60。

负载结构：

{
  "id": "session_id_here",
  "title": "Session Title",
  "state": "AWAITING_PLAN_APPROVAL",
  "url": "https://jules.google.com/session_url"
}

运行监视器：

通过 npx：

JULES_API_KEY=your_key JULES_WATCH_WEBHOOK_URL=https://hooks.slack.com/services/... npx -y google-jules-mcp-server watch

通过本地克隆：

JULES_API_KEY=your_key JULES_WATCH_WEBHOOK_URL=https://hooks.slack.com/services/... node build/index.js watch

也可以直接从已构建的检出目录运行监视器：

JULES_API_KEY=your_key JULES_WATCH_WEBHOOK_URL=https://your.webhook.url/here node build/watch.js

PM2 配置示例（ecosystem.config.js）：

module.exports = {
  apps: [
    {
      name: "jules-watcher",
      script: "npx",
      args: "google-jules-mcp-server watch",
      env: {
        JULES_API_KEY: "your_key",
        JULES_WATCH_WEBHOOK_URL: "https://your.webhook.url/here",
        JULES_WATCH_INTERVAL_SECONDS: "60",
      },
    },
  ],
};

systemd 服务示例（/etc/systemd/system/jules-watcher.service）：

[Unit]
Description=Jules Session Watcher

[Service]
ExecStart=/usr/bin/npx google-jules-mcp-server watch
Environment="JULES_API_KEY=your_key"
Environment="JULES_WATCH_WEBHOOK_URL=https://your.webhook.url/here"
Restart=always

[Install]
WantedBy=multi-user.target

Docker 单行命令示例：

docker run -d --name jules-watcher \
  -e JULES_API_KEY=your_key \
  -e JULES_WATCH_WEBHOOK_URL=https://your.webhook.url/here \
  node:22 npx -y google-jules-mcp-server watch

速率限制与配额

Jules 会根据订阅等级限制任务配额（Free：每天 15 个／并发 3 个；Google AI Pro：每天约 75 个／并发 15 个；Google AI Ultra：每天约 300 个／并发 60 个）。即使任务失败，也会计入配额；配额按滚动 24 小时窗口计算。

开发

完整的环境设置和 PR 检查清单请参阅 CONTRIBUTING.md，社区规范请参阅 CODE_OF_CONDUCT.md。

npm run dev              # tsc --watch
npm run lint              # eslint
npm run format             # prettier --check
npm run typecheck           # tsc --noEmit
npm test                    # vitest run
npm run test:coverage        # vitest run --coverage (enforces threshold)
npm run test:watch            # vitest
npm run inspector               # MCP Inspector — exercise tools without a full client

测试策略

单元测试使用 MSW 在网络层拦截 HTTP 请求，而不是直接模拟客户端模块——这意味着测试会覆盖 core/http-client.ts 自身的逻辑（身份验证标头、重试／退避、错误映射、Retry-After 解析），而不只是基于它构建的处理程序。tests/fixtures/ 中的夹具将经过验证的真实 Jules API 响应结构编码为 MSW 模拟响应正文；由于真实客户端会在测试时通过 Zod 模式解析这些响应，模式与夹具不匹配会立即导致测试套件失败。

tests/smoke/live-api.smoke.test.ts 是一个可选择启用的只读冒烟测试，用于测试真实 Jules API（仅调用 jules_list_sources，以避免消耗任务配额）。它不会纳入 npm test 和 CI，仅通过以下命令运行：

JULES_LIVE_SMOKE_TEST=1 npm run test:smoke

添加新工具

1. 为该资源添加／扩展 schemas.ts（Zod 模式和推断类型）。
2. 在该资源的 client.ts 中添加 API 调用。
3. 在 format.ts 中添加格式化逻辑，并在 tools.ts 中添加处理程序和 registerTool 调用。
4. 为客户端、格式化和工具处理程序层添加由 MSW 支持的测试。

故障排除

• 未显示工具：检查客户端配置中的绝对路径，确认 build/index.js 存在（npm run build），然后完全重启客户端。
• “JULES_API_KEY environment variable is required”：客户端服务器配置 env 块中未设置密钥。
• “No repositories connected to Jules”：访问 https://jules.google.com，连接你的 GitHub 账户并授予仓库访问权限。
• 401／403／404：401 表示 API 密钥无效（通过上方的设置链接重新生成）；403 表示权限不足或已超出配额；404 表示会话或仓库 ID 不存在。
• 每次调用都失败，并提示 Unexpected token '', "..." is not valid JSON：你使用的是 0.2.3 或更早版本，且处于代理之后；压缩过的响应仍以压缩状态到达解析器。请升级到最新版本。
• 出现 Network error connecting to Jules API: fetch failed，或调用一直挂起：如果你的网络需要代理，服务器可能无法获取代理配置。仅在 shell 中导出代理变量并不够——客户端会将服务器作为子进程启动，因此应将 HTTPS_PROXY 添加到该服务器的 env 块中。请参阅企业代理环境。

安全

发现漏洞？请参阅 SECURITY.md，了解如何私下报告。

API 参考

• 基础 URL：https://jules.googleapis.com/v1alpha
• 身份验证：X-Goog-Api-Key 标头
• Jules Web 应用：https://jules.google.com

许可证

MIT

更新日志

请参阅 GitHub Releases——每个已发布版本都会自动生成一个版本说明，并按变更类型分类。