noracu

noracu

Claude、Cursor、または任意の MCP クライアントから、element_index で macOS アプリと Playwright ブラウザーを操作できるローカル MCP サーバーです。実験的に、Apple の iPhone ミラーリングを通じて実機の iPhone も操作できます（Mac 上で OCR を実行し、正規化座標でタップします）。API キーは不要で、サーバーからテレメトリーが送信されることもありません。

中国語の説明は README.zh-CN.md をご覧ください。

1 つの stdio MCP サーバーです。エージェントはツリーのスナップショットを取得し、インデックス付きの要素リストを受け取ってから、生のピクセルではなく element_index でクリックや入力を行います。Mac とブラウザーのどちらでも、同じ「観察してから操作する」流れです。実験的な iPhone レイヤーでは、OCR テキストと正規化座標を使って、同じ「観察 → 操作」のループを実行します。

browser_snapshot はインデックス付きの ARIA ツリーを返し、browser_click は element_index で操作します。Mac レイヤーも同じループ（mac_ax_state → mac_click）を実行します。ハイライトボックスは demo/record-browser.mjs によるオーバーレイであり、製品の機能ではありません。このデモに iPhone レイヤーは含まれていません。

できること

1 つの MCP サーバーに、3 つの操作レイヤーがあります。

レイヤー	ツール	操作対象	状態
Mac	9（mac_*）	cliclick、screencapture、JXA System Events	安定
ブラウザー	12（browser_*）	Playwright（永続プロファイル）	安定
iPhone	14（phone_*）	バンドルされた imctl ドライバー（Python + pyobjc）経由の iPhone ミラーリング	実験的

iPhone レイヤーは実験的な機能で、ドライバー（imctl、imctl/ 内）も同梱されています。Apple の iPhone ミラーリングが必要で、iPhone をロックした状態で Mac の近くに置く必要があります。また、pyobjc をインストールした python3 も必要です。element_index ではなく、OCR で画面を認識し、正規化座標で操作します。pyobjc がない場合、phone_* ツールはインストールコマンドを含む「imctl unavailable」という 1 行のエラーを返しますが、Mac レイヤーとブラウザーレイヤーには影響しません。観察と操作の用語は、ChatGPT のコンピューター操作機能で広く知られるようになったアクションと観察の分離に沿ったもので、ローカルのオープンなツールで再実装されています。

noracu を選ぶ理由

noracu はモデルではなく、ローカルで操作を実行します。何をするかは MCP クライアント（Claude Desktop、Claude Code、Cursor）が判断し、このサーバーはこのマシン上で観察と操作を行うだけです。

• サーバーはすべてこのマシン上で動作します。 クラウドサービスも、API キーも、テレメトリーも、インストール後のスクリプトもありません。唯一の実行時依存関係は Playwright です。noracu 自体はネットワーク通信を行いません。自動で行われる通信は、初回の browser_launch 時に一度だけ実行される Chromium のダウンロードです（NORACU_DISABLE_AUTO_INSTALL=1 で無効にできます）。ブラウザーは指定したページを引き続き取得します。また、MCP クライアントは引き続き、スクリーンショットや OCR テキストなどのツールの結果を、使用するモデルに送信します。
• ピクセルではなく、意味に基づいて操作します。 観察結果として、アクセシビリティツリー（Mac）または ARIA ツリー（ブラウザー）がインデックス付きリストで返されます。スクリーンショットではなくテキストです。操作には element_index を指定します。インデックスは 30 秒後に有効期限が切れ、クリック前に対象（ブラウザーではタグ名／名前／href／位置、Mac では最前面のアプリ）が再検証されます。参照が古くなっている場合、誤った対象をクリックする代わりに element_no_longer_valid が返されます。ツリーだけでは不十分な場合に、スクリーンショットを利用できます。
• 1 つのループで、3 つの対象を操作します。 Mac のネイティブアプリと永続プロファイルを使うブラウザーは、element_index プロトコル（ツリーを観察し、インデックスで操作）を共有します。実験的な iPhone レイヤーは、Apple の iPhone ミラーリング上で同じ「観察 → 操作」ループを実行し、OCR テキストと正規化座標を使用します。これは、iPhone が Mac にアクセシビリティツリーを公開していないためです。
• 実際のセッションを使用します。 ホスト型の VM ではなく、ログイン済みのブラウザープロファイルや Mac アプリを使用します。クラウドでのコンピューター操作と比べて、どちらが常に信頼性が高いということはありません。それぞれ異なる失敗の仕方をします。noracu は画面をこのマシン上にとどめます。
• 確実に無効化できるスイッチを備えています。 NORACU_READ_ONLY=1（観察のみ、デフォルトで拒否）、NORACU_DISABLE_EVAL=1、およびデフォルトでブロックされる file:// に対応しています。セキュリティを参照してください。
• 検証可能です。 エンドツーエンドのチェックが 39 件（npm test）、macos-latest での CI、MIT ライセンスを採用しています。サーバー全体は 1 つのファイル src/server.mjs で構成されています。

適していないケース： 複数のブラウザータブやセッションが必要な場合（現時点では単一セッションのみ）、macOS を使用していない場合（Mac レイヤーと iPhone レイヤーは macOS 専用、ブラウザーレイヤーはクロスプラットフォーム）、または完成した iPhone レイヤーがすぐに必要な場合（提供されていますが実験的です。また、Apple は EU で iPhone ミラーリングを提供していません）。ブラウザー自動化だけが必要なら、noracu v0.1 にはないタブ管理機能やセレクター API を備えた playwright-mcp が適しています。noracu は、1 つのエージェントがブラウザーを離れて Mac アプリも操作する必要がある場合に向いています。

クイックスタート

最初に成功させるのは mac_ax_state（またはブラウザーのスナップショット）です。クリックや phone_* ツールではありません。初日に最も多い失敗は、macOS の権限をホストアプリではなく node に付与してしまうことです。権限は完全に終了して再起動した後にのみ適用されます。

1. インストール（Node ≥ 20、インストール後スクリプトはありません）：

npm install noracu          # server at node_modules/noracu/src/server.mjs
brew install cliclick       # required for Mac input (mac_click/type/key/paste)

ソースからインストールする場合：git clone https://github.com/sgInnora/noracu.git && cd noracu && npm install && npm test（ハードウェア依存のチェックをスキップするには NORACU_CI=1 を追加します）。

2. MCP クライアントに追加します — src/server.mjs には絶対パスを指定してください。 Finder／Dock から起動した GUI アプリはシェルの PATH を引き継がないため、node バイナリにも絶対パス（which node）を指定してください。node、npx、noracu のみを指定する場合は、GUI の PATH に Node が必要です。そうでない場合は ENOENT で失敗します。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）／Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "noracu": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/ABSOLUTE/PATH/TO/noracu/src/server.mjs"]
    }
  }
}

Claude Code：claude mcp add noracu -- /ABSOLUTE/PATH/TO/node /ABSOLUTE/PATH/TO/noracu/src/server.mjs

which node で Node のパスを確認してください（Apple Silicon：/opt/homebrew/bin/node、Intel：/usr/local/bin/node、nvm：バージョン付きのパス）。Node がすでに GUI の PATH にある場合に限り、次の簡易設定も使えます："command": "npx", "args": ["-y", "noracu"]。

続いてホストアプリを完全に終了（メニューバーのアイコンも含む）してから、再起動してください。 ツールリストが読み込まれれば、トランスポートは動作しています。まだ権限は必要ありません。

3. macOS の権限は node ではなく、ホストアプリに付与してください。 システム設定 → プライバシーとセキュリティ → アクセシビリティと画面収録（macOS 15：「画面とシステムオーディオの収録」）→ ホスト（Claude Desktop／Cursor／使用するターミナル）を有効にします。noracu はここには表示されません。権限を付与した後、ホストを終了して再起動してください。

4. 確認します。 Finder を前面に表示し、mac_ax_state（引数なし）を呼び出すと、インデックス付きのアクセシビリティツリーが返されます。インデックスの有効期間は 30 秒です。ブラウザーの簡易テスト（アクセシビリティ権限は不要）：browser_launch（初回実行時に NORACU_DISABLE_AUTO_INSTALL=1 が設定されていない場合は Chromium をダウンロードします）→ browser_navigate → browser_snapshot → インデックスを指定して browser_click。

トラブルシューティング

症状	原因／対処
mac_* がエラー -1719 で失敗する	ホストアプリにアクセシビリティ権限が付与されていません。権限を付与してから、ホストを終了して再起動してください
スクリーンショットが真っ黒になる	ホストに画面収録権限が付与されていません。権限を付与してから、ホストを終了して再起動してください
cliclick に関する ENOENT が表示される	brew install cliclick（または NORACU_CLICLICK を設定してください）
GUI ホストからの spawn node／npx が ENOENT になる	設定に node の絶対パスを指定してください。nvm／volta／homebrew の shim は GUI の PATH にありません
初回使用時に browser_launch が停止する	Chromium の初回ダウンロード中です。または自動インストールが無効です（NORACU_DISABLE_AUTO_INSTALL=1）→ npx playwright install chromium を実行してください
phone_* が imctl unavailable: no python3 with pyobjc found と表示する	python3 に pyobjc をインストールする（python3 -m pip install pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-AppKit。通常は Homebrew の python3 を使用します）か、NORACU_PYTHON を設定してください。iPhone レイヤーを参照してください
phone_* が mirror_not_live: …（「Connection Paused」、「iPhone in Use」）で拒否される	ミラーが一時停止中か、iPhone のロックが解除されています。iPhone をロックして Mac の近くに置き、phone_launch を呼び出してください（Resume をクリックします）
入力したテキストのスペースが変わる（例：「no ra cu」）	CJK 入力メソッドが有効です。mac_type の代わりに mac_paste を使用してください
element_no_longer_valid	スナップショットが 30 秒より古いか、UI が変更されています。mac_ax_state／browser_snapshot を再実行し、新しいインデックスを使用してください

Node 18 は起動時に拒否されます。Node ≥ 20 を使用してください。Claude Desktop は画面ごとに noracu プロセスを 1 つ起動する場合があります（例：チャット用と 2 つ目の画面用）。ブラウザープロファイルは共有されるため、ブラウザーの起動は一度に 1 つの画面からのみ行ってください。

実行例の全容：docs/usage.md。

iPhone レイヤー（実験的）

noracu は Apple の iPhone Mirroring を通じて、実際の iPhone を操作できます。エージェントは Mac 上で OCR を使って画面を確認し（phone_screenshot、phone_ocr、phone_find）、0～1 の正規化座標で操作し（phone_tap、phone_swipe、phone_scroll）、貼り付けて入力し（phone_type）、アプリを名前で開きます（phone_open）。これは element_index とは異なります。iPhone は Mac にアクセシビリティツリーを公開しないため、タップは OCR がテキストを検出した位置に行われます。ドライバー（imctl、Python、MIT、約 1,000 行）は imctl/ に含まれています。

Apple の要件（support.apple.com/120421）：Apple シリコンまたは T2 チップを搭載し、macOS 15 以降を実行する Mac、パスコードが設定され、iOS 18 以降を実行する iPhone、両方が 2 ファクタ認証を有効にして同じ Apple Account にサインインしていること、Bluetooth と Wi-Fi がオンになっていること、Mac がインターネット接続を共有しておらず、AirPlay または Sidecar を使用していないこと。iPhone はロックされ、Mac の近くにある必要があります。ロックを解除するか、iPhone Mirroring を終了すると、セッションは終了します。iPhone Mirroring は現在 EU では利用できません。一度に接続できるのは Mac 1 台と iPhone 1 台です。カメラとマイクはミラーリングされません。

無人セッション： iPhone Mirroring → Settings の「Authenticate automatically」を有効にすると、パスワードの入力を求められずにセッションを開始できます。代わりに、ロック解除された Mac を使える人なら誰でも iPhone を開けるようになります。

Python： ドライバーには、pyobjc（Quartz、Vision、AppKit）をインポートできる python3 が必要です。NORACU_PYTHON を設定するか、noracu が最初の phone_* 呼び出し時に /opt/homebrew/bin/python3、/usr/local/bin/python3、python3、/usr/bin/python3 を一度だけ順に確認します。Apple の /usr/bin/python3 には通常 pyobjc が含まれていません。Homebrew の python3 と python3 -m pip install pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-AppKit を使うのが、一般的な動作環境です。

ミラーリングの状態： phone_status は live（iPhone の画面がストリーミングされている）、overlay（「Connection Paused」や「iPhone in Use」など、iPhone Mirroring が代わりに表示するテキスト）、paused（そのオーバーレイに Resume ボタンが表示されている）を報告します。検出ではウインドウの構造を読み取り、テキストは読み取りません。ミラーリングがライブでない間は、phone_tap、phone_longpress、phone_swipe、phone_scroll、phone_type、phone_key、phone_open はオーバーレイをタップせずに mirror_not_live を返し、phone_ocr と phone_find は出力の先頭に警告を付けます。ミラーリングは操作がない状態が続くと一時停止します。phone_launch を実行すると前面に表示され、Resume をクリックします。

プライバシー： iPhone に表示されるもの（通知、メッセージ、メール、ワンタイムコードなど）はすべて、MCP クライアントからモデルに送信されるツール出力になります。Focus をオンにし、開始前に無難なアプリを開いて、まずは NORACU_READ_ONLY=1 で開始してください（phone_status、phone_screenshot、phone_ocr、phone_find は引き続き使用できます。iPhone への入力はすべて拒否されます）。Mirroring の設定後は、iPhone の通知も Mac に届きます。

最初に試す手順： phone_status → live が true でない場合は phone_launch → phone_screenshot → phone_ocr → phone_find + phone_tap。

既知の制限： タップは OCR がテキストを検出した位置に行われるため、同じラベルが複数ある場合や読み取りを誤った場合は、意図しない場所をタップすることがあります。phone_scroll はトラックパッド風のスクロールイベントでリストを移動します（縦方向の phone_swipe ドラッグではリストをスクロールできません。ホーム画面のページ切り替えなどのジェスチャーに使用してください）。テストした 1 つの環境（iOS 27.0.1 の iPhone 17 Pro Max、macOS 26.6.2 の Mac）では、iPhone Mirroring が View のサイズにかかわらず、ウインドウより約 17% 大きく iPhone を表示するため、右端の列と最下段の行が切れて操作できませんでした。ウインドウを別のディスプレイに移動する、メインディスプレイを変更する、再起動する、といった方法でも変化はありませんでした。主な原因として iOS 27 と macOS 26 のバージョン不一致が疑われます。画面の端付近をタップして反応しない場合は phone_screenshot を確認してください。phone_open は Spotlight にアプリ名を入力し、完全一致する候補があればタップします。一致しない場合はホーム画面に戻ります。phone_home と phone_app_switcher は iPhone Mirroring のメニュー（英語版 macOS）を使用し、接続中であれば Python なしで動作します。

環境変数

変数	デフォルト	目的
NORACU_READ_ONLY	未設定	=1 観察専用：12 個の観察ツールとブラウザーのライフサイクルツールを許可するデフォルト拒否の許可リストです。クリック／入力／貼り付け／キー操作／eval の各ツールはすべて拒否されます
NORACU_DISABLE_EVAL	未設定	=1 にすると、呼び出された際に browser_evaluate（任意の JS）がエラーを返します（ツール一覧には引き続き表示されます）
NORACU_ALLOW_FILE_URL	未設定	=1 にすると、browser_navigate で file:// URL を開けるようになります（デフォルトではブロックされています）
NORACU_DISABLE_AUTO_INSTALL	未設定	=1 にすると、初回の browser_launch 時に Chromium を自動インストールしません
NORACU_CLICLICK	/opt/homebrew/bin/cliclick	cliclick バイナリのパス
NORACU_PYTHON	自動検出	同梱の iPhone ドライバーで使用する python3 です。pyobjc（Quartz、Vision、AppKit）をインポートできる必要があります。未設定の場合は、/opt/homebrew/bin/python3、/usr/local/bin/python3、python3、/usr/bin/python3 の順に、最初に動作するものが使われます
NORACU_IMCTL_DIR	同梱の imctl/	ドライバーの場所を上書きします（開発専用）

セキュリティ

noracu は MCP クライアントと同じ権限で動作します。このマシン上の実際のブラウザーをクリック、入力、貼り付け、操作します。サンドボックスはなく、リモートでの承認プロンプトもありません。サーバーのエントリーに以下を設定してから、ホストを完全に終了し、再度開いてください。

"env": { "NORACU_READ_ONLY": "1", "NORACU_DISABLE_EVAL": "1" }

• NORACU_READ_ONLY=1 は安全な初回実行モードです。12 個の名前からなる許可リスト（観察ツールと browser_launch／browser_navigate／browser_close）に含まれないツールはすべて拒否されます。クリック、入力、貼り付け、eval の各ツールはすべて拒否されます。browser_navigate は許可リストに含まれているため、引き続き URL を読み込めます。
• NORACU_DISABLE_EVAL=1 にすると、browser_evaluate は呼び出された際にエラーを返します（tools/list には引き続き表示されます）。スナップショット、クリック、入力は引き続き動作します。
• file:// は NORACU_ALLOW_FILE_URL=1 を設定しない限り拒否されます。そのため、ブラウザーエージェントがそこへ移動して ~/Documents を読み取ることはできません。（初回の移動先 URL はスキームをチェックしますが、リダイレクトはチェックしません。詳しくは SECURITY.md を参照してください。）
• フォーカスガード： mac_type／mac_paste／mac_key に app を渡すと、そのアプリが最前面にない限り入力は拒否されます。app を省略するとガードは無効になります。
• 古い要素への保護： element_index は座標ではありません。30 秒後に期限切れとなり（element_no_longer_valid）、ブラウザーでのクリック時にはタグ／名前／href／位置が再確認されます。また、スナップショット取得後に最前面のアプリが変わっている場合、Mac でのクリックは拒否されます。
• iPhone の画面はモデルへの入力です： phone_screenshot／phone_ocr／phone_find は、通知、メッセージ、ワンタイムコードなど、スマートフォンに表示されている内容をそのまま返します。Focus と中立的なアプリを使用し、まず NORACU_READ_ONLY=1 で開始してください（スマートフォンの観察は許可されますが、入力は拒否されます）。ミラーリングが一時停止中の場合も、スマートフォンへの入力は拒否されます（mirror_not_live）。
• インジェクション対策済みの JXA： 文字列パラメーターはスクリプトに埋め込まず、argv のデータとして osascript に渡されます。唯一の数値（AX の読み取り深度）は、使用前に 1～10 の範囲に制限されます。回帰テスト済みです。

これらの設定を行っても、観察した内容が信頼できるものになるわけではありません。スクリーンショットのテキスト、アクセシビリティ名、ページの内容は、モデルにとって信頼できない入力です。それらにタスクを上書きさせないでください。脅威モデルの全容と脅威ごとの対応状況については、SECURITY.md を参照してください。

ツールとドキュメント

• ツールの完全なリファレンス：docs/tools.md（実行中のサーバーから自動生成）
• 使用方法の手順：docs/usage.md
• アーキテクチャ：docs/architecture.md

ロードマップ

• ブラウザー：タブ管理（一覧表示／選択／閉じる）
• 操作の語彙（ブラウザー）：hover、set_value、wait_for
• トークン使用量削減のためのスナップショット差分 — 測定待ち
• iPhone：OCR 領域に対する element_index の使用と、タップ前のテキスト再確認

メンテナンス

単独でメンテナンスしており、SLA はありません。Mac レイヤーには macOS 15 以降が必要です。iPhone レイヤーには Apple silicon または T2 搭載 Mac、iOS 18 以降、iPhone ミラーリングが必要です（EU では利用できません）。ブラウザーレイヤーは Playwright が動作する環境であればどこでも動作します。

ライセンス

MIT — LICENSE を参照してください。