Arc Control (macOS)

arc-control-mcp

macOS 上の Arc ブラウザーを操作する MCP サーバーです。タブ、ページ遷移、ページの読み取り、DOM 操作、スクリプト実行に対応します。

同梱の「Control Chrome」MCP サーバーでは Arc を指定できないために作られました。Arc のスクリプティング辞書は Chrome のものに似ていますが、重要な箇所で正確に異なります。

対象ユーザー： Arc で動作させたい Mac 上のエージェント（Claude Code やその他の MCP クライアント）を利用している方です。新しい自動化プロファイルではなく、すでにサインインしているブラウザーを使えます。ページを読み取り、フォームに入力し、クリックし、JavaScript を実行し、自分のタブとは別に専用のタブを管理します。

対象外： クロスプラットフォームまたはクロスブラウザーのツールではありません。Apple Events 経由で、1 つのオペレーティングシステム上の 1 つのブラウザーを操作します。また、スクリーンショット、信頼された入力、コンソール／ネットワークのキャプチャには、オプションのDevTools エンジンを使用できます。ヘッドレスモードはありません。Docker イメージもありませんし、実現もできません。Apple Events はコンテナの境界を越えないため、コンテナから Mac 上で実行されている Arc にアクセスする方法がないからです。これは個人プロジェクトの 0.4.0 であり、以下に記載する既知の Arc の制限事項は実際に存在します。

要件

• macOS
• Arc がインストールされていること
• Node 20 以降（CDP ツールには、組み込みの WebSocket を利用するため Node 22 以降が必要です。Node 20 では明確なメッセージを表示して失敗しますが、それ以外の機能は引き続き動作します）

実行時依存関係は @modelcontextprotocol/sdk と zod の 2 つです。ビルド手順はありません。

インストール

クローンする必要はありません。どの MCP クライアントでも npx を使ってサーバーを起動でき、アップグレードにも @latest を使います。次回の起動時に新しいリリースが適用されます。

{
  "mcpServers": {
    "arc": {
      "command": "npx",
      "args": ["-y", "arc-control-mcp@latest"]
    }
  }
}

重要

この設定だけでは不十分です。macOS の権限を 2 つ許可する必要があり、そのうち 1 つは Arc 自体の設定で許可するもので、許可を促す表示は出ません。両方を許可するまで、サーバーは正常に起動しても、すべてのツールが失敗します。新規インストールが正常に動作しない場合、その原因である可能性が最も高いのはこれです。2 つの macOS 権限（次のセクション）を確認してください。

package.json では "os": ["darwin"] が宣言されているため、Linux または Windows ではインストールが EBADPLATFORM で停止します。インストールが成功した後、最初の Apple Event で失敗することはありません。環境変数は args と並ぶ env オブジェクトに設定します。環境変数を参照してください。

claude mcp add arc --scope user -- npx -y arc-control-mcp@latest

claude mcp get arc

{
  "servers": {
    "arc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "arc-control-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"arc","command":"npx","args":["-y","arc-control-mcp@latest"]}'

git clone https://github.com/DB-25/arc-control-mcp.git
cd arc-control-mcp
npm install
claude mcp add arc-dev --scope user -- node "$PWD/src/index.js"

{
  "mcpServers": {
    "arc-dev": {
      "command": "node",
      "args": ["/absolute/path/to/arc-control-mcp/src/index.js"]
    }
  }
}

MCP クライアントを使わずにインストールを確認できます。どちらの呼び出しも Arc にアクセスしないため、以下の権限を許可する前でも動作します。

npx -y arc-control-mcp@latest --version
npx -y arc-control-mcp@latest --help   # tool count and environment variables

2 つの macOS 権限

どちらも一度だけ許可を求められますが、ここを確認すべきだと知らないと、どちらも原因が分かりにくい形で失敗します。

1. オートメーション。 システム設定 > プライバシーとセキュリティ > オートメーションで、サーバーを実行するアプリ（ターミナル、iTerm、Claude Code、エディター）の下にある Arc を有効にします。これが許可されていないと、最初の Apple Event で失敗し、何も動作しません。
2. Apple Events からの JavaScript を許可。 Arc > 設定 > 詳細設定で許可します。これが許可されていない場合も、タブやウィンドウのツール（一覧表示、切り替え、閉じる、URL を開く）は動作しますが、ページの内容にアクセスする操作はすべて失敗します。テキストの取得、HTML の取得、クリック、スクリプトの実行はできません。

どちらの失敗も、生の AppleScript コードではなく説明付きのエラーに変換されるため、どちらを修正すべきか通知されます。

3 つ目の権限として、任意でアクセシビリティ（同じアプリに対するシステム設定 > プライバシーとセキュリティ > アクセシビリティ、およびシステムイベントのオートメーション）があります。この権限があると、サーバーはエージェントのウィンドウを 2 台目のディスプレイに配置し、Arc が別のウィンドウを前面に表示した場合に、あなたのウィンドウを再び前面に戻せます。許可しなくてもすべての機能は動作しますが、エージェントのウィンドウは移動されず、フォーカスも復元されません。また、最初の open_url でその旨が一度通知されます。以下のユーザーアクティビティゲートには権限は必要ありません。

Chrome サーバーをそのまま再利用しない理由

Arc のスクリプティング辞書は Chrome のものに似ていますが、次のような違いがあり、Chrome サーバーをそのままでは動作させられません。

Chrome サーバーはすべての ID に対して parseInt(tab_id) を呼び出すため、Arc ではタブ ID を受け取るすべてのツールが AppleScript に到達する前に失敗します。また、AppleScript のカンマ区切りの出力を分割するため、カンマを含むタイトルや URL が壊れてしまいます。

設計

設計上、制限は設けていません。エージェントがアクセスできるものは何でも操作できます。任意のタブ、任意のスペース、任意の JavaScript が対象です。デフォルト設定はユーザーのブラウジングを妨げないように選ばれていますが、アクセスを遮断するものはありません。

• 暗黙の対象：tab_id を指定しない呼び出しでは、このエージェントが開いたタブが使われます。読み取り専用ツールの場合は、Arc で現在アクティブなタブにフォールバックします。すでに開いているページを読むのは便利で無害だからです。タブを変更するツールはフォールバックしません。エージェント自身のタブがない場合は拒否されるため、引数を省略しただけでエージェントが作業中のタブを移動したり再読み込みしたりすることはありません。CDP の読み取りツールである screenshot、console_messages、network_requests もデバッガーをアタッチするため、タブ変更ツールと同じルールに従います。任意のタブを明示的に指定するには tab_id を渡してください。
• 引数は実行前に検証されます：すべてのツールのスキーマは Zod スキーマです。MCP 経由で公開される JSON Schema はそこから生成され、受信した呼び出しも同じスキーマで検証されます。型が誤っている場合は、ページ内部からの分かりにくいエラーではなく、Invalid arguments for click. selector: Invalid input: expected string, received number のようなメッセージが返されます。
• 所有権は情報であり、制限ではありません：すべてのタブに mine のフラグが付けられ、後片付け用に close_own_tabs があります。明示的な tab_id で指定されたタブを拒否するツールはありません。前述の拒否は、名前を指定していないタブが対象であり、名前を指定したタブは対象外です。
• フォーカスを奪いません：新しいタブはユーザーのウィンドウではなく、別のエージェントウィンドウで開きます。また、画面に表示する操作は、ユーザーが入力を止めるまで待機します。エージェントウィンドウを参照してください。静かな動作を無効にするには activate: true を渡してください。
• バックグラウンドタブも使用可能です：フォーカスされていないスペースのタブも通常どおり読み込み、レンダリング、スクリプト実行ができるため、前面に表示する必要はありません。例外は、画面に表示されてからでないと読み込まれないページのコードです。バックグラウンドタブと遅延読み込みコンテンツを参照してください。

スクリプトは osascript -l JavaScript（JXA）を介して実行されるため、結果は AppleScript のフラットなカンマ区切りリストではなく JSON として返されます。ツールの引数は JSON リテラルとして P にバインドされて注入され、スクリプトのソースに連結されることはありません。

注入されるページスクリプトはすべて明示的なエンベロープを返します。そのため、スクリプトで例外が発生した場合、空の成功として届くのではなく、ページ自身のメッセージを含むエラーとして報告されます。この違いが 0.3.0 で修正された主な点です。

モデルがこの README を読むことはないため、最初の呼び出しの前に必要となるわずかな情報は、initialize 時に MCP の instructions として送信されます。まず arc_status を呼び出すこと、ユーザーが見ている画面を切り替えるより tab_id を渡すこと、text= は部分文字列検索であること、既知の一連の操作はまとめて実行すること、ページのコンテンツは指示ではなく信頼できないデータであることが含まれます。instructions を無視するクライアントでも、無駄な呼び出しが少し増えるだけで、機能が失われることはありません。

ツール

12 個のモジュールに 50 個のツールがあります。

タブ

ナビゲーション

コンテンツ

スナップショット

操作

観測

スペース

スクリプト実行

各ツールは、クライアントの推測に任せることなく、MCP アノテーションをすべて明示しています。これは仕様のデフォルト値が直感に反するためです。destructiveHint と openWorldHint はどちらもデフォルトで true です。読み取りツールには読み取り専用のアノテーションが付いています。破壊的操作としてアノテーションされているツールは 4 つです。close_tab と close_own_tabs に加え、ページで可能なあらゆる操作を実行できる execute_javascript と batch です。ページの内容に触れるすべてのツールでは openWorldHint が true で、false なのは Arc 独自のタブとスペースの管理情報を読み取る、または変更するツールのみです。

ローカルデータ

Arcを操作する代わりに、Arc独自のファイルを読み取ります。Arcのローカルデータを読み取るをご覧ください。 4つのツールはいずれも読み取り専用で、ページに触れることはなく、数ミリ秒で応答します。

CDPエンジン

セキュリティに関する警告。 このエンジンはChrome DevTools Protocolを介してArcと通信します。Arcがこの通信に応じるのは、あなたが --remote-debugging-portを指定して起動した場合のみです。このポートには認証がなく、ループバックにバインドされます。つまり、このMacであなたのユーザーとして実行されるプロセスは、そこからArcを操作し、 すべてのページを読み取り、サインイン済みのセッションをプロンプトなしで使用できます。Arcはデフォルトではこの状態にならず、ここに記載した内容があなたに代わって有効化することもありません。また、Sparkleによる更新でArcが再起動すると、このフラグは引き継がれません。ARC_MCP_CDP=0でエンジンを無効にし、Arcを通常どおり再起動してポートを閉じてください。有効にする前に scripts/arc-cdp-setup.mdをお読みください。

上記のすべてはApple Eventsと挿入されたJavaScriptを介して動作しますが、次の3つの厳しい制限があります。イベントはすべて合成イベント（isTrustedがfalse）であり、スクリーンショットは取得できず、ページのコンソールとネットワークは見えません。CDPエンジンはこれらの制限を取り除きます。サーバーではデフォルトで有効ですが、Arcがポートを公開するまでは動作しません。最初のCDPツールが127.0.0.1:9222を確認します（確認に失敗した場合、その結果は10秒間記憶されるため、呼び出しのたびに確認する必要はありません）。応答がない場合、すべてのCDPツールはセットアップ手順とともにok: falseを返し、それ以外のすべてのツールは従来どおりに動作します。

セットアップには3つのコマンドを使用します（詳細、オプションのlaunchd修復機能、セキュリティ上のトレードオフについては、scripts/arc-cdp-setup.mdをご覧ください）。

# 1. Quit Arc (Cmd-Q). It restores your tabs.
open -a Arc --args --remote-debugging-port=9222    # 2. relaunch with the flag
curl -s 127.0.0.1:9222/json/version                 # 3. verify
arc-control-mcp --check-cdp                         # or probe with the CLI, changing nothing

仕組みは次のとおりです。

• タブの取得には引き続き Apple Events を使用します。 CDP は既存のページにのみ接続し、ターゲットを作成することはありません（Target.createTarget を呼び出すと Arc がクラッシュします）。
• タブは URL やタイトルではなく、ノンスで対応付けます。 Apple Event 側がページの DOM に一度限りのランダム値（data-arc-mcp-tab）を書き込み、CDP 側がそれを探します。ノンスが見つかった後にのみターゲットを使用するため、9222 ポートでリッスンしている別の Chromium を誤って操作することはありません。タブ自身のアドレス（フラグメントと末尾のスラッシュは無視）にあるターゲットのみを調べ、リダイレクトがまだ完了していない場合に備えて、短い待機の後にもう一度だけ調べます。また、ガードレールで禁止されているオリジンのターゲットは一切調べません。対応付けはタブごとにキャッシュされ、ナビゲーションによって属性が削除されるため、使用のたびに再検証されます。
• ここでも Refs とセマンティックセレクターを使用できます。 ref=e12、role=、label=、placeholder= は、ref テーブルがある Apple Event 側で最初に解決されます（CDP からは Arc の分離されたワールドを参照できません）。その後、対象の要素に一度限りの data-arc-mcp-target 属性が設定されます。続く DevTools 呼び出しはその要素に対して実行され、処理後に属性が削除されます。古い ref は click とまったく同じように失敗し、reResolved が報告されます。
• タブのルールに変更はありません。 tab_id はほかの場合と同様に機能します。また、タブを変更するツールが、現在表示しているタブにフォールバックすることはありません。screenshot、console_messages、network_requests は読み取り専用ですが、デバッガーを接続するため、tab_id がない場合も同じルールに従います。エージェントが開いたタブを使うか、拒否するかのどちらかであり、現在表示しているタブは使いません。
• キャプチャは初回接続時に開始されます。 console_messages と network_requests で取得できるのは、CDP ツールが初めてタブに触れた後に発生したものだけです。CDP から履歴を読み戻すことはできないため、観測したい操作を行う前にいずれかを呼び出してください。
• 機密情報は保持しません。 リクエスト本文とレスポンス本文は保存しません。ヘッダーの取得はオプトインであり、cookie、authorization、set-cookie と、名前に token、secret、key、session、signature のいずれかを含むヘッダー、または x-auth で始まるヘッダーは、受信時に伏せ字にされます。クエリにはトークンが含まれることが多いため、include_query を設定しない限り、URL はクエリ文字列とフラグメントを除いて表示されます。 | ツール | 目的 | |---|---| | cdp_status | エンジンを使用できるかどうかを確認します。ポート、ブラウザー、ページターゲット数、セキュリティ警告を示します。何も応答しない場合は、設定手順とともに ok: false を返します。 | | screenshot | PNG または JPEG（quality）を MCP の画像コンテンツとして取得します。ビューポート、full_page（上限 16384 px）、または selector で指定した要素を撮影します。バックグラウンドタブでも、前面に切り替えずに動作します。前面に切り替えるのは activate: true を指定した場合のみで、その場合は open_url と同様に一時停止するまで待機し、その後、ウィンドウとアプリケーションを元に戻します（focusRestored）。 | | trusted_click | 要素をスクロールして表示した後、要素の中央を実際にクリックします（isTrusted が true）。button、click_count（2 を指定すると dblclick）を設定できます。無効なコントロールは拒否し、coveredBy を報告します。 | | trusted_type | 実際に文字を入力します。デフォルトでは 1 回の insertText を実行します。per_key: true を指定すると、文字ごとに keydown、keypress、input、keyup を実行します（入力中の検索に対応）。clear を指定すると内容を置き換えます。フィールドにフォーカスできない場合は、何も入力せず ok: false を返します。 | | trusted_press_key | 修飾キーを含む実際のキーイベントを送信します。Enter でフォームを送信し、Tab でフォーカスを移動し、Meta+A ですべて選択します。その後、フォーカスされている要素を報告します。 | | trusted_hover | 実際にポインターを移動し、:hover が適用されたかどうかを報告します。 | | drag | セレクター間、または座標間で、押下、段階的な移動、解放を行います。ネイティブの HTML5 ドラッグ＆ドロップに対応しています。 | | upload_file | 絶対パスを指定してファイル入力にファイルを設定します。相対パス、存在しないパス、通常ファイルではないパス、認証情報、シェル履歴、メール、ブラウザープロファイルのパス（~/.ssh、~/.aws、Arc と Chrome のプロファイル、Messages、Mail、Safari、Keychains、.env と .env.*、.zsh_history、.bash_history など）は、パスの大文字・小文字にかかわらず拒否します。 | | handle_dialog | alert、confirm、prompt、beforeunload を承認または閉じます。他のツールは、開いているダイアログで停止する代わりに、そのダイアログを報告します。 | | console_messages | バッファーされた console.*、捕捉されなかった例外、ブラウザーのログエントリーを取得します。level でフィルタリングできます。 | | network_requests | 各リクエストのメソッド、URL（include_query を指定しない限りクエリー文字列なし）、ステータス、種類、タイミング、サイズを取得します。include_headers は任意で指定でき、ヘッダーは編集されます。本文は取得しません。 |

知っておくべき制限：要素セレクターで操作できるのはトップレベルのドキュメントのみで、iframe は対象外です。macOS では Meta+ ショートカットはページではなくメニューバーで処理されるため、編集コマンドとともに送信されます。また、JavaScript ダイアログが開いている間は、handle_dialog で閉じるまでページにアクセスできません。

セレクター

すべてのセレクター引数には、次のいずれかを指定できます。

• querySelectorAll にそのまま渡される CSS セレクター、または

• text=Some label。表示テキストに一致します。これは部分一致で、 大文字と小文字は区別されません。完全一致が優先されるため、 text=Save は「Save and close」というラベルのボタンよりも、「Save」と いうラベルのボタンを優先します。最も内側にある一致が、その祖先より 優先されます。単一の要素に対して動作するツールは、一致した件数を報告 するため、曖昧なラベルでも気付かずに済むことはありません。テキスト全体 の一致を必須にするには exact: true を、別の一致を選ぶには nth を 指定してください。

• snapshot で取得した ref=e12。

• role=button[name="Save"]。ARIA ロールまたは暗黙のロールと、完全一致する アクセシブル名を指定します。または role=button[name~="sav"] のように、 大文字と小文字を区別しない部分一致も指定できます。アクセシビリティ ツリーから隠されている要素は一致しません。

• label=Email と placeholder=Search。ラベルが示すコントロール、 またはそのプレースホルダーを持つフィールドを指定します。text= と同様に 部分一致し、完全一致が優先されます。

execute_javascript には、単独の式（document.title）または文の本体 （const rows = [...]; return rows.length）を指定できます。どちらの形式が 使われたかは form として報告され、値は "expression" または "statement" です。文の本体で値を返せるのは return を使った場合だけです。 let n = 2; n * 3 は null として返され、「return を追加してください」という 注記が付きます。ここで 6 を生成するには、ページ内で eval を使う必要が あり、厳格な Content-Security-Policy を設定しているサイトでは動作しない ためです。構文エラーは Arc に接続する前に Node で検出され、実際のパーサー メッセージとともに拒否されます。

form フィールドが重要なのは、正当な null とスクリプトの失敗を区別 できるようにするためです。以前はこれが不可能でした。DOM ノードや window など、JSON で有用な表現ができない値の場合は、単なる {} ではなく、その 理由を説明する note がレスポンスに含まれます。

スナップショットと refs

snapshot はスクリーンリーダーと同じようにページを読み取り、すべての要素に ref を付与するため、モデルはセレクターを推測せず、読み取った内容をもとに 操作できます。

- heading "Sign in" [level=1] [ref=e3]
- textbox "Email" [ref=e4] value="[email protected]" (required)
- button "Sign in" [ref=e5] (disabled)

次に、selector: "ref=e5" を指定して click します。セレクターを受け取る すべてのツールでは、ref のほか、role=、label=、placeholder= の形式も 使用できます。

• ロールは ARIA または要素の暗黙のロールから取得されます。名前は aria-labelledby、aria-label、<label>、alt、title、 placeholder、テキストコンテンツから取得され、最大 100 文字です。状態は (checked, disabled, expanded, selected, required) のように表示されます。 パスワードの値は決して表示されません。
• 非表示のサブツリー（display: none、aria-hidden、inert）はスキップ され、名前のないラッパーは折りたたまれます。開いているシャドウルートと 同一オリジンの iframe は走査されます。クロスオリジンのフレームには、 未検査であることが示されます。
• ref は安定しており、同じ要素はスナップショット間で同じ ref を保持します。 ページが再レンダリングされ、要素が同一の要素（同じロール、名前、同一の 兄弟要素内での位置）に置き換えられた場合、古い ref は再解決され、結果には reResolved: true が含まれます。要素がなくなった場合、または同一の兄弟 要素の数が変わって一致対象を推測するしかない場合、呼び出しは失敗し、 ref が古くなっているため再度スナップショットを取得するよう通知されます。 state: "absent" を指定した wait_for_selector は、なくなった ref を absent として扱います。
• diff: true を指定すると、このタブの前回のスナップショットと同じ オプションで比較し、unchanged、または追加・変更された行と削除された行を 返します。
• boxes: true を指定すると、getBoundingClientRect で計測した [box=x,y,w,h] と [in-viewport] または [offscreen] が追加されます。 バックグラウンドのタブでは IntersectionObserver が実行されないためです。

制限事項：ref は 1 つのドキュメントに属するため、ページ遷移後は再度 スナップショットを取得してください。閉じたシャドウルートは読み取れません。 ref の再解決ではロールと名前が照合されるため、同じラベルの行が並べ替えられる と、ref が同じ要素の別の行を指すことがあります。確認が必要な場合は reResolved がその目印になります。

アクション後の待機

click、fill、select_option、press_key は MutationObserver を開始して操作を行い、その後、DOM に settle_ms（デフォルトは 300、スキップするには 0）の間変化がない状態になるか、1500 ms が経過するまでポーリングします。結果には settledMs（最後に変化があった時刻。アクションからの相対時間）、settled、mutations が含まれます。上限に達してもページの変化が続いている場合は、settled: false が返されます。この待機により osascript の往復が 1 回余分に発生します。また、バックグラウンドタブではブラウザーがページのタイマーを抑制するため、settled: true の後に遅延した更新が届くことがあります。

ページヘルパーライブラリ

execute_javascript は、組み込みツールと同じヘルパーライブラリを使って実行され、A にバインドされています。利用できるのは A.all、A.one、A.click、A.setValue、A.describe、A.visible、A.key です。そのため、A.all('text=Sign in').length が動作し、コンソールでできることはすべてここでもできます。

batch

osascript の起動には数百ミリ秒かかるため、CDP を使う場合よりも、ここではバッチ処理が重要です。

{"steps": [
  {"tool": "fill",  "args": {"selector": "#user", "value": "db"}},
  {"tool": "fill",  "args": {"selector": "#pass", "value": "..."}},
  {"tool": "click", "args": {"selector": "text=Sign in"}},
  {"tool": "wait_for_selector", "args": {"selector": ".dashboard"}}
]}

バッチ内では、タブはステップごとに繰り返し報告されず、バッチ全体で 1 回だけ報告されます。バッチの途中で実際に変化した場合にのみ、再度報告されます。

タブ ID は UUID 文字列で、タブを閉じて開き直すと変わるため、以前の ID を再利用せず、list_tabs を呼び出してください。

Arc のローカルデータを読む

Arc は、サイドバー、アーカイブ、履歴を ~/Library/Application Support/Arc/ 以下のファイルに保存します。4 つのツールがこれらを直接読み取ります。これにより、Apple Events では取得できない情報（ピン留めの有無、フォルダー、タブが最後にアクティブだった時刻、アーカイブ）を取得でき、すべてのタブを Apple Events で走査するのに数秒かかるのに対し、数ミリ秒で処理できます。

利用する前に知っておくべきこと：

• 反映には遅れがあります。 Arc はこれらのファイルを変更のたびではなく、定期的に書き込みます。そのため、直近 1 分ほどの間に開いた、閉じた、または移動したタブは、見つからなかったり、古い情報だったりする可能性があります。各結果には asOf（ファイルの変更時刻）と、その旨を示す注記が含まれます。最新の状態を確認するには list_tabs を使ってください。
• ID は対応しています。 サイドバー項目の id は、list_tabs が報告する tab_id です。そのため、find_stale_tabs の結果をそのまま close_tab に渡せます。match_live: true を指定した sidebar_tree は、各タブを開いているタブと照合します。
• エラーは明示されます。 ファイルがない場合、JSON が無効な場合、またはこのサーバーが対応していないファイル形式のバージョン（サイドバーとアーカイブはバージョン 1）の場合、推測で結果を返すことなく、理由とともに ok: false を返します。読み取るテーブルに必要な列がない履歴データベースも、同様にエラーになります。
• 読み取り専用です。 ここで Arc のファイルに書き込むことはありません。Arc の実行中はロックされる履歴データは、一時コピーから読み取られ、呼び出しが返る前に削除されます。使用するのは macOS に付属する /usr/bin/sqlite3 です。依存関係は追加されません。
• 日付。 Arc は 2001 年からの秒数で保存し、結果は ISO 8601 UTC 形式です。

プライバシー

これらのファイルには、ユーザーが閲覧した内容がすべて記録されています。タブのタイトルと URL はモデルのコンテキストに入り、そこからクライアントが送信する先へ渡されます。

• sidebar_tree には include_urls: false を指定でき、結果を小さくして情報を減らせます。

• search_history はオプトイン方式です。サーバーの環境変数に ARC_MCP_ALLOW_HISTORY=1 が設定されていない場合、ok: false を返し、有効化する方法を示します。

  claude mcp add arc --scope user -e ARC_MCP_ALLOW_HISTORY=1 -- npx -y arc-control-mcp@latest
  

  profile を渡さない場合は、Default プロファイルのみを読み取ります。profile を渡す場合は、User Data 以下のフォルダー名（Profile 1 など）を指定します。非表示のページ（リダイレクト、サブフレーム）は除外されます。結果数には上限があり、limit のデフォルトは 25、最大値は 500 です。

• ARC_MCP_ARC_DATA_DIR を設定すると、コピーやテスト用のフィクスチャディレクトリなど、別のディレクトリをツールに指定できます。

環境変数

ガードレール

ブラウザーの操作を完全には信頼できないエージェント向けの任意の制限です。すべて環境変数で、起動時に一度だけ読み込まれるため、エージェントがセッション中に制限を緩めることはできません。MCP クライアントのサーバー設定で指定してください。ルールに誤記がある場合、または監査ファイルに書き込めない場合、ガードレールが気付かれないまま無効になるのではなく、変数名を示してサーバーの起動を停止します。arc_status には有効な設定が表示されるため、モデルは制限に抵触する前に把握できます。

claude mcp add arc --scope user \
  --env ARC_MCP_ALLOWED_ORIGINS='example.com,*.example.com,localhost:3000' \
  --env ARC_MCP_BLOCKED_ORIGINS='admin.example.com' \
  --env ARC_MCP_AUDIT_LOG="$HOME/arc-audit.jsonl" \
  -- npx -y arc-control-mcp@latest

オリジンルール。 エントリーには host、*.host、scheme://host[:port]、file://（任意のファイル URL）、about:（そのスキームの任意の URL）を指定できます。ホスト名だけを指定した場合は、スキームやポートにかかわらず、そのホスト名と完全一致するものに適用されます。*.example.com はサブドメインのみと一致するため、example.com も指定してください。一致判定には解析済みのホスト名を使用し、部分文字列は使いません。そのため、example.com.evil.test は example.com と一致しません。許可リストを指定すると、リストにないものは空白のタブも含めてすべて拒否されます。ブロックルールは常に優先されます。

• open_url は、ページを開く前に対象 URL がチェックされます。
• ページを変更するその他すべてのツール（click、fill、fill_form、type、hover、select_option、press_key、scroll、execute_javascript、go_back、go_forward、reload_tab、stop_loading、capture_start、およびCDP エンジンのページ変更ツールである trusted_click、trusted_type、trusted_press_key、trusted_hover、drag、upload_file、handle_dialog）は、最初に対象タブの現在の URL を読み取り、ルールに合致しない場合は拒否されます。検査したタブが実際に操作されるタブとなるため、tab_id が渡されていない場合も同様です。ページを変更する呼び出しごとに osascript の呼び出しが 1 回追加されます。batch では、各ステップの実行時にチェックされます。
• 読み取りツールは、ARC_MCP_BLOCK_READS=1 でない限り許可されます。CDP の読み取りツール（screenshot、console_messages、network_requests）も対象です。また、activate: true の場合、スクリーンショットはほかの表示操作と同様にアクティビティゲートによって保留されます。
• CDP エンジンは、ルールで禁止されたオリジンのページをプローブ（ページに接続してスクリプトを実行）しません。タブの対象を特定するためであっても同様です。
• Arc のタブ自体を管理するだけのツール（close_tab、switch_to_tab、close_own_tabs、focus_space）は、オリジンによる制限の対象外です。
• 拒否された呼び出しは、ok: false、blocked: true、rule、およびルール名とオリジンを示すエラーを返します。ページ遷移ツール（open_url、戻る、進む、再読み込み）の実行後は、タブの最終 URL も再度チェックされます。ブロック対象のオリジンにリダイレクトされた場合、遷移自体は行われているため、失敗として報告されます。

把握しておくべき制限事項：チェックは呼び出し前に行われるため、その間にページが自動で遷移しても、次の呼び出しまで検出されません。エージェントがすでにスクリプトを実行できるページは、任意の宛先にリクエストを送信できます。このルールが制限するのはエージェントが操作するページであり、そのページ自身のコードが取得するものではありません。

読み取り専用モード。 ARC_MCP_READ_ONLY=1 にすると、読み取り専用と注釈されたツールだけが公開され、それ以外のツールは名前を指定して呼び出しても拒否されます。

監査ログ。 ARC_MCP_AUDIT_LOG=<path> を指定すると、ページを変更する呼び出しごとに JSON の行を 1 行追記します。記録されるのは time、tool、tab ID、origin（スキームとホストのみ。パスやクエリは記録されません）、ok、error です。入力値、入力されたテキスト、スクリプトコードは記録されません。ページ独自のエラーメッセージにはこれらが含まれる場合があるため、fill、fill_form、type、select_option、press_key、execute_javascript、trusted_type、trusted_press_key、upload_file、handle_dialog の失敗は、理由を記録せず、失敗したことだけを記録します。batch の各ステップは個別の呼び出しとして記録されます。拒否された呼び出しも記録されます。ファイルは所有者のみがアクセスできる状態で作成されます。

エージェントウィンドウとアクティビティゲート

エージェントがブラウザーを操作している間も、自分の Arc ウィンドウで作業を続けられ、エージェントが決してキーボードを奪わないようにすることが目的です。

1 つのエージェントウィンドウ

エージェントのタブは、あなたのウィンドウではなく、専用の Arc ウィンドウに表示されます （ARC_MCP_WINDOW=dedicated。デフォルトです）。その ID は状態ディレクトリに保存され、 すべてのラベルとセッションで共有されます。ウィンドウの検索または作成は、プロセス間ロックのもとで 実行されます。ウィンドウは常に最大 1 つで、保存されたウィンドウが実際に閉じられた場合にのみ 新しいウィンドウが作成されます。最小化されたウィンドウや、Arc が visible: false と報告するだけの ウィンドウは、閉じられたわけではありません。アクセシビリティ機能を使えば最小化と閉じた状態を 区別できます。アクセシビリティ機能がない場合、サーバーは 2 つ目のウィンドウを誤って作成する リスクを避けるため、ウィンドウはまだ存在すると判断します。慎重に扱う理由は、Arc では Arc が 最前面にあり、ウィンドウにフォーカスがある場合にのみ「ウィンドウを閉じる」が機能し、 ウィンドウにはアクセシビリティ対応の閉じるボタンがないため、ここから余分なウィンドウを 閉じられないからです。エージェントウィンドウを閉じると、次の open_url で新しいウィンドウが 作成されます。

配置（ARC_MCP_WINDOW_PLACEMENT。アクセシビリティ機能が必要です。作成時に一度だけ適用されるため、 自分で移動したウィンドウはその位置に留まります）：

ARC_MCP_WINDOW=space を設定すると、以前の設計に戻ります。タブはあなたのウィンドウ内の Agent スペースに追加されます（Arc ウィンドウは分離の境界ではありません。1 つのスペースを 表示する各ウィンドウに同じタブが一覧表示されるため、ここで分離するにはスペースを使うしか ありません）。

ウィンドウまたはタブを作成すると、そのウィンドウが前面に表示されます。Arc が最前面にある場合、 入力中のウィンドウからキーボードフォーカスが移ります。そのため open_url は、最初に フォーカスがあったウィンドウを記録し、処理後に元に戻します（結果の focusRestored: true）。 Arc 独自のスクリプトではこれを実行できないため、アクセシビリティ機能を介して処理します。 さらに、前面にあったアプリケーションも記録します。Arc が前面に移動した場合（ウィンドウの作成、 Arc のコールド起動、activate を指定した screenshot）、そのアプリケーションを再びアクティブにし、 復元できたことを確認します。置き換えられたものがすべて元に戻った場合にのみ focusRestored が true になり、復元できなかったものは focusRestoreError に示されます。 アクセシビリティ機能がない場合、配置もウィンドウの復元も行われません（アプリケーションの復元は 引き続き実行されます）。また、open_url はアクセシビリティ機能の許可方法を示す accessibilityNote を一度だけ返します。Arc が起動していない間は、アクセシビリティ機能に 問い合わせる対象がありません。これは許可が不足しているという意味ではありません。Arc は通常どおり 起動され、ウィンドウが作成されます。

アクティビティゲート

画面上の表示やフォーカス中のウィンドウを変更する可能性がある操作を行う前に、サーバーは ARC_MCP_IDLE_MS（1500 ms）の間アイドル状態になるまで待機します。250 ms ごとに確認し、最大 ARC_MCP_IDLE_WAIT_MS（15 s）まで待ちます。アイドル時間は ioreg -c IOHIDSystem から取得する HID カウンターの値で、権限は必要ありません。一度も操作を中断しない場合、ツールは ok: false, userActive: true を返し、Mac を使用中であることを示すエラーを返すため、エージェントは後で再試行します。何かが開かれたり移動されたりすることはありません。この呼び出しがエージェントウィンドウを作成した後に入力を始めた場合は、結果にそのことが示されます（agentWindow: { created: true, id }）。空のウィンドウはそのまま保持され、次の呼び出しで再利用されるため、ウィンドウが重複することはありません。成功時の結果には waitedForUserMs が含まれます。待機はプロセス間ロックを取得する前に行われ、ロックを保持している間には行われないため、別のセッションが入力中のユーザーを待たされることはありません。ARC_MCP_IDLE_MS=0 にすると無効になります。

batch 全体がゲート対象になるわけではありませんが、各ステップで同じ確認が行われます。そのため、switch_to_tab のステップは待機しますが、fill のステップは待機しません。アイドル時間を読み取れない場合、ゲートは呼び出しを通過させ、そのことを userIdleCheck で通知します。

表示されたままになるもの

• エージェントウィンドウ自体は画面上に表示されます。2 台目のディスプレイでは邪魔になりません。ディスプレイが 1 台で auto の場合は、見えるウィンドウになります。
• open_url は一時的にエージェントウィンドウを前面に表示します。アクセシビリティが有効な場合は、ユーザーのウィンドウが再び前面に戻されます。無効な場合は、Arc がエージェントウィンドウにフォーカスを維持することがあります。
• activate: true、switch_to_tab、focus_space は、意図的に画面に表示されます。
• little_arc は Little Arc ウィンドウを開きます。このウィンドウは、その後 Arc から公開されません。
• Arc が起動していない状態で起動すると、Arc が表示されます。arc_status やその他の読み取り操作では、Arc は起動されません。
• tab_id で指定したタブを閉じると、そのウィンドウの表示が変わることがあります。また、エージェントウィンドウの最後のタブを閉じると、そのウィンドウも閉じることがあります。
• ページが独自に音声を再生したり（window.open やダイアログを表示したり）することはありますが、このツールで制御することはできません。ページスクリプトが移動できるのは、タブ内の DOM フォーカスのみです。

エージェント同士も分離されています。各エージェントはサーバーの独自のコピーを実行し、所有権はセッションごとに追跡され、ARC_MCP_LABEL で名前が付けられます。両方が同じラベルを使用していても、一方のエージェントの list_tabs scope=own と close_own_tabs から、もう一方のタブが見えることはありません。以前の実行が異常終了して残ったタブは、arc_status で古いタブとして報告されます。要求された場合に限り、close_own_tabs include_stale=true で閉じられるため、再起動によって実行中の別エージェントのタブが閉じられることはありません。すべてのエージェントが 1 つのエージェントウィンドウを共有します。

Arc の既知の制限事項

2026 年 8 月に確認済みです。Arc のアップデート後に再テストする価値があります。これらは Arc の動作であり、ここで決定したものではありません。

• タブの location（topApp / pinned / unpinned）の設定は書き込み可能と表示されますが、常に -10000 で失敗するため、ピン留め／ピン留め解除ツールはありません。
• ウィンドウを閉じても何も起こらないため、サーバーがウィンドウを作成することはありません。
• スペースの作成は何も起こらないまま終了するため、スペースは手動で作成します。
• ウィンドウの作成時に mode: "incognito" を指定しても無視されます。
• Little Arc のタブは Arc.windows に表示されないため、作成後に読み取ったり閉じたりできません。
• 閉じたウィンドウは、activeTab がエラーを起こす不可視の幻影として Arc.windows に残るため、検索時には visible() でフィルタリングします。
• space.tabs には topApp のお気に入りが含まれないため、それらの space は null と報告されます。list_spaces は topAppCount を報告するため、その数は list_tabs の結果と一致します。
• window.tabs() による一括取得は -1700 を発生させますが、一括でのプロパティ読み取り（window.tabs.id()）は機能し、Apple Events の数も約 10 分の 1 になります。
• Arc.execute はページの値を JSON エンコード したものを返すため、文字列は引用符付きで返され、返却前に引用符を取り除きます。
• Arc の goBack はバックグラウンドタブでは何もしないため、go_back と go_forward は代わりにページ独自の履歴 API を使用し、URL が変わったことを確認します。

バックグラウンドタブと遅延コンテンツ

バックグラウンドタブでは document.hidden が報告され、タブ内の要素が表示範囲にスクロールされることもないため、IntersectionObserver のコールバックや loading="lazy" のコンテンツがいつまでも読み込まれない場合があります。この方法でウィジェットのコードを読み込むサイトもあります。GitHub では「Customize your pins」ダイアログがバックグラウンドタブで開きますが、リストは読み込まれず、強制的に読み込ませても「Save pins」を有効にするスクリプトは実行されません。

click はページが無視したクリックを報告するのではなく、無効なコントロールのクリックを拒否し、タブが非表示であることも通知します。有効にする操作を行った後もコントロールが無効のままの場合は、switch_to_tab を実行して（ユーザーにもその操作が見えます）、再試行してください。

合成イベントの制限事項

click、fill、press_key は、注入された JavaScript から合成イベントをディスパッチします。信頼済みイベント（event.isTrusted）を条件とするウィジェットは、この方法では操作できません。Arc の execute javascript では、実際の入力イベントを注入する方法がありません。解決策は CDP エンジン（trusted_click、trusted_type、trusted_press_key、drag）ですが、Arc を DevTools フラグ付きで起動した場合に限られます。フラグなしの場合は、以下の回避策を使用してください。

Wikipedia の検索ボックスで確認済みです。fill は値を正しく設定しますが、候補のドロップダウンは開きません。文字ごとのイベントも効果がありません。そのため type は、イベントを受け取るウィジェット（isTrusted を確認しない input または keydown のハンドラー）向けに用意されており、信頼済みイベントを必要とするウィジェットを操作する方法ではありません。

回避策は機能し、通常は本来やりたかった操作でもあります。

• submit: true を指定して fill を実行すると、Enter キーが押されてページが移動します。または
• open_url で検索 URL に直接移動します。

ウィジェットが候補リスト、ホバープレビュー、ドラッグにしか反応しない場合は、合成イベントツールでは反応しないと考えてください。信頼済みイベントを使うツールを使用してください。

タブの読み込みとstop_loading

タブの読み込み中、Arc はexecute javascriptに応答しません。呼び出しは osascript の30秒のタイムアウトまで停止し、読み込み中に実行した呼び出しは、読み込み完了後も戻ってこないことがあります。停止したリクエストや、サーバーが応答しない<iframe>があると、タブはその状態のまま無期限に留まります（応答を開いたままにする localhost サーバーを使用し、Arc 1.165 で確認）。stop_loadingは Arc の AppleScript のstopコマンドで停止ボタンを押します。その後はスクリプトが再び動作し、ページにはそれまでに表示された内容が残ります。

Arc ではすべてのタブに、即座に応答するloadingプロパティがあり、wait_for_loadはページに何かを問い合わせる前にこのプロパティを確認します。読み込み中のタブはready: "loading"を返し、タイムアウト時にはその旨とstop_loadingを案内するため、呼び出しが終わるまで停止し続けることはありません。他のページツールはこのプロパティによる制限を受けません。クリックやopen_urlによってページ遷移が始まった直後は、まずwait_for_loadを呼び出してください。

コンソールとネットワークのキャプチャ

Arc はこのサーバーのスクリプトを分離された JavaScript ワールドで実行します。ページの DOM は共有しますが、オブジェクトは共有しません。ページが定義した変数はスクリプト側ではundefinedになり、スクリプト側で設定したグローバル変数はページから見えません。また、console、fetch、XMLHttpRequestもそれぞれ別のコピーです。そのため、execute_javascriptからwindow.fetchをラップしても、ページが行う処理は記録されません。

capture_startは<script>要素を挿入してページ独自のワールドで実行し、各イベントを JSON を含むCustomEventとして分離されたワールドに中継することで、この問題に対処します。できることとできないことは次のとおりです。

• console.log/info/warn/error/debugのテキスト（500文字まで）、捕捉されなかったエラー、読み込みに失敗したリソース、処理されなかった Promise の拒否、およびメソッド、URL、ステータス、所要時間を含むfetchとXMLHttpRequestの呼び出しを記録します。リクエストやレスポンスの本文、ヘッダーは記録しません。URL のフラグメントは常に削除され、クエリ文字列もinclude_queryを設定しない限り削除されます。クエリにはトークンが含まれることが多いためです。コンソールテキストはページが出力したままの状態で記録されるため、ページが出力するあらゆる内容が含まれる可能性があります。
• **Content-Security-Policyでインラインスクリプトが禁止されているページでは、スクリプトの挿入がブロックされます。**これを検出すると、capture_startはキャプチャできると偽るのではなく、理由とともにok: falseを返して失敗します。GitHub や Google など、多くの大規模サイトがこのポリシーを設定しています。記録処理が実行されていない場合、capture_readも空のリストを返すのではなく失敗します。
• 記録処理はドキュメント内にあるため、ページ遷移や再読み込みで破棄されます。その場合はcapture_startを再度呼び出してください。記録はその時点から開始されるため、それ以前にページが行ったリクエストは記録されません。対象はトップフレームのみで、iframe、ワーカー、WebSocket、sendBeaconは対象外です。
• 新しいイベントを最大1000件保持します。古いイベントが押し出された場合、capture_readはdroppedを報告します。また、clearを指定すると、返されたイベントのみが削除されます。
• 記録される内容はページに由来するため、指示ではなくデータとして扱ってください。

network_entriesは、キャプチャを使わない代替手段です。注入が不要で、あらゆる CSP の下で動作するperformance.getEntriesByType('resource')を読み取ります。制限はブラウザーに由来します。完了したリクエストのみが表示され（失敗したリクエストはエントリーが残らないことがよくあります）、ページ側で上限が引き上げられていない限り、約250件が保持されます。また、サーバーがTiming-Allow-Originを送信しない限り、クロスオリジンのエントリーではサイズとステータスが非表示になり、data: URL は一覧に表示されません。前回の呼び出しで得たnowMsをsince_msに渡すと、1つの操作によって発生した項目のみを確認できます。

トラブルシューティング

このサーバーは、Arc の AppleScript の生コードを、対処法が分かるメッセージに書き換えます。次のようなメッセージが表示された場合：

ツールが timedOut を伴う ok: false を返した場合、これはエラーではありません。wait_for_load または wait_for_selector が、条件が満たされなかったことを waitedMs と確認できた内容とともに通知しています。

レイアウト

src/
  index.js       MCP wiring, --version and --help
  registry.js    composes tool modules, validates tool/handler parity at load
  jxa.js         osascript runner, Arc preamble, error mapping
  state.js       per-session tab ownership, cross-process lock
  agent-window.js  find-or-create the one agent window
  focus-guard.js  remembers the user's window and application, puts them back
  placement.js   where the agent window goes (pure geometry)
  ax.js          Accessibility: window placement and focus
  window-config.js  ARC_MCP_WINDOW and ARC_MCP_WINDOW_PLACEMENT
  user-activity.js  the idle gate (HID idle time)
  arc-data.js    reads Arc's sidebar and archive files
  arc-history.js reads Arc's history database from a temporary copy
  policy.js      guardrails: origin rules, read-only mode, audit log
  page-lib.js    helper library injected into the page as `A`
  result.js      turns a handler result into MCP content (JSON text, or an image)
  cdp/           the DevTools engine: client, engine, tab mapping, capture, input
  tools/
    shared.js      common schemas and run helpers
    tabs.js        list, switch, close, status
    navigation.js  open, back, forward, reload, wait for load, stop loading
    open-dedicated.js  open_url into the agent window
    content.js     text, html, structured queries, links, page info
    interact.js    click, fill, select, keys, scroll, wait for selector
    input.js       fill_form, hover, type
    wait.js        wait for text
    capture.js     console and network capture, resource timing
    spaces.js      Arc spaces
    scripting.js   raw JavaScript and batch
    local.js       sidebar, stale tabs, archive and history from Arc's own files

    cdp.js         screenshots, trusted input, console and network capture
scripts/
  arc-cdp-setup.md   how to opt in, and what it costs in security
  arc-cdp-healer.sh  optional launchd helper that re-applies the flag after an update

モジュールを追加するには、tools/<name>.js を作成して tools と handlers をエクスポートし、registry.js に登録します。レジストリは、起動時に名前の重複、ハンドラーのないツール、ツールのないハンドラーを検出するとエラーを発生させます。CONTRIBUTING.md を参照してください。

プロジェクトのドキュメント

• CHANGELOG.md。0.3.0 で修正された内容も記載されています
• CONTRIBUTING.md
• SECURITY.md。脅威モデルも記載されています。このサーバーは設計上、実際にログインしているブラウザーで任意の JavaScript を実行します
• docs/agent-review-2026-08-31.md。0.3.0 の対象範囲を定めたレビューです
• LICENSE、MIT