google-jules-mcp-server

google-jules-mcp-server

Claude、Cursor、VS Code Copilot、その他のMCPクライアントからGoogleのJulesコーディングエージェントを操作する方法をお探しなら、このサーバーがその橋渡しをします。google-jules-mcp-serverは、Jules API（v1alpha）全体を13個のツールとして公開する非公式のModel Context Protocolサーバーです。これにより、アシスタントはチャットを離れることなく、セッションの作成、ステータスの確認、計画の承認、生成されたプルリクエストの取得を行えます。

複数のリポジトリでJulesを同時に実行する開発者は、AIアシスタントに非同期ワークフロー全体を管理させるためにこのサーバーを利用しています。タスクを開始し、後で進捗を確認し、完了したらPRリンクを受け取れるため、Julesのウェブアプリに切り替えて進捗を見守る必要はありません。すべてのレスポンスは実行時にZodスキーマで検証されるため、Jules APIのレスポンスに変更があると、後続コードを気づかないまま壊すのではなく、明確にエラーとして通知されます。

GoogleのJules AIコーディングエージェント向けModel Context Protocol（MCP）サーバーです（非公式）。ClaudeなどのAIアシスタントから、Jules API v1alphaを通じて非同期のコーディングタスクを作成・管理できます。

概要

Julesは、隔離されたクラウドVM上で開発タスクを実行するGoogleのAIコーディングエージェントです。コードの生成、バグの修正、テストの作成、依存関係の更新、複数ファイルにまたがるリファクタリングを行います。このサーバーは、リポジトリのソース、セッションのライフサイクル、アクティビティログを網羅する13個のMCPツールとして、Jules APIの全機能を公開します。

タスクは非同期で実行され、複雑さに応じて通常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レスポンスに変更があると、後続処理で気づかないままundefinedが生成されるのではなく、JulesResponseValidationErrorとして明確にエラーになります。

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 のエージェントモード）— ターミナルから実行：

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	1 回の呼び出しでセッションを作成し、完了まで待機します
jules_list_activities	セッションの詳細なアクティビティログを取得します
jules_get_activity	ID を指定して単一のアクティビティを取得します

出力サイズとページネーション

これらのツールが返すすべての内容はアシスタントのコンテキストウィンドウに入ります。また、自律的なコーディングセッションでは、数百ステップに及ぶ非常に長いエージェントメッセージ、進捗の説明、計画が生成されることがあります。そのため、サーバーは返す内容に上限を設け、内容を途中で切り詰めた場合はその旨をインバンドで通知します。これにより、アシスタントは残りを取得するかどうかを判断できます。

ツール	上限
jules_get_status	最近のアクティビティダイジェスト内の各アクティビティにつき100文字
jules_list_activities	エントリーあたり約800文字、ページあたり約10,000文字
jules_get_activity	8,000文字

jules_list_activities の上限に達したエントリーには、jules_get_activity で再取得するために必要な sessionId と activityId が記載されています。このツールでは、同じアクティビティが、単一アクティビティ用のより大きな上限で返されます。つまり、10倍の余裕がありますが、無制限ではありません。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. ポーリング — jules_get_status を使って10〜30秒ごとにポーリングします。
3. 監視 — jules_list_activities で詳細な進捗を監視します。
4. 取得 — 状態が COMPLETED になったら、jules_get_session_output でプルリクエストの URL を取得します。

タスクの監視を依頼すると、アシスタントがこのポーリングループを自動的に処理します。

セッションウォッチャー（停止したセッション）

停止したセッション（例：AWAITING_PLAN_APPROVAL や AWAITING_USER_FEEDBACK）のポーリングで LLM クライアントのトークンを消費したくない場合は、単独で動作するセッションウォッチャーを実行できます。MCP クライアントとは独立して動作し、セッションが停止すると JSON ペイロードを Webhook に送信します。

必須の環境変数：

• 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：1日あたり15件／同時実行3件、Google AI Pro：1日あたり約75件／同時実行15件、Google AI Ultra：1日あたり約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 またはリポジトリ ID が存在しないことを意味します。
• すべての呼び出しが Unexpected token '', "..." is not valid JSON で失敗する：0.2.3 以前のバージョンでプロキシの背後から利用している場合、gzip 圧縮されたレスポンスが圧縮されたままパーサーに届いています。最新リリースにアップグレードしてください。
• Network error connecting to Jules API: fetch failed が表示される、または呼び出しが停止する：ネットワークでプロキシが必要な場合、サーバーにプロキシが認識されていません。シェルで環境変数をエクスポートするだけでは不十分です。クライアントは子プロセスとしてサーバーを起動するため、HTTPS_PROXY はそのサーバーの env ブロックに設定してください。企業プロキシの背後での設定を参照してください。

セキュリティ

脆弱性を発見した場合は、非公開での報告方法について SECURITY.md を参照してください。

API リファレンス

• ベース URL：https://jules.googleapis.com/v1alpha
• 認証：X-Goog-Api-Key ヘッダー
• Jules ウェブアプリ：https://jules.google.com

ライセンス

MIT

変更履歴

GitHub Releases を参照してください。公開された各バージョンには、変更の種類ごとにまとめたリリースノートが自動生成されます。