Claude For Safari

Claude for Safari

MCP プロトコルを介して Claude Desktop から Safari を操作できるようにします。ページの移動、コンテンツの読み取り、要素のクリック、フォームへの入力が可能で、「Claude in Chrome」と同様に動作します。

アーキテクチャ

Claude Desktop  (MCP stdio)
      ↕  JSON-RPC
  bridge/bridge.js  (Node.js)
      ↕  WebSocket  ws://localhost:45678
Safari Extension background.js  (MV2)
      ↕  browser.tabs / executeScript
    Active Safari tab

---

リポジトリ構成

claudeForSafari/                  ← git root
├── .gitignore
├── README.md
├── bridge/                       ← Node.js bridge (MCP ↔ WebSocket)
│   ├── bridge.js
│   ├── package.json
│   └── package-lock.json
└── app/                          ← Xcode project
    ├── claudeExtension.xcodeproj
    ├── claudeExtension/          ← Swift host app (macOS)
    └── claudeExtension Extension/
        └── Resources/            ← SINGLE SOURCE for extension files
            ├── manifest.json
            ├── background.js
            ├── popup.html / popup.js / popup.css
            ├── images/
            └── _locales/

ルール： 拡張機能のファイルはすべて、直接 app/claudeExtension Extension/Resources/ 内で編集してください。独立した safari-extension/ フォルダーはありません。

---

必要条件

• macOS 13 以降（Ventura 以降）
• Xcode 16 以降
• Node.js v20 以降 — まだインストールしていない場合は nodejs.org を参照してください
• Apple 開発者アカウント（ローカルでの使用には無料アカウントで十分です）
• MCP 対応の Claude Desktop

---

インストール

ステップ 1 — リポジトリをクローンする

git clone [email protected]:Lyosis/claudeForSafari.git
cd claudeForSafari

ステップ 2 — ブリッジの依存関係をインストールする

cd bridge
npm install
cd ..

ステップ 3 — Xcode で拡張機能をビルドする

1. Xcode で app/claudeExtension.xcodeproj を開きます
2. claudeExtension スキーム（ホストアプリ）を選択します
3. 実行先として My Mac を選択します
4. Cmd+R を押します — Xcode がアプリをビルドして起動します

macOS にバナーが表示されます："claudeExtension が Safari 拡張機能を追加しようとしています" → Open Safari Preferences をクリックして、拡張機能を有効にします。

ステップ 4 — Safari で拡張機能を有効にする

1. Safari → 設定（Cmd+,） → 機能拡張タブ
2. claudeExtension にチェックを入れます
3. 右側の列で → すべての Web サイトで許可

この権限がないと、ページへのスクリプトの挿入はエラーを表示せずに失敗します。

ステップ 5 — Claude Desktop を設定する

次のファイルを開く（または作成する）：

~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers の下に safari エントリーを追加します：

{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": [
        "/absolute/path/to/claudeForSafari/bridge/bridge.js"
      ]
    }
  }
}

/absolute/path/to/ を、リポジトリをクローンした実際のパスに置き換えてください。

Claude Desktop の PATH に node が含まれていない場合は、フルパスを使用します：

which node   # e.g. /usr/local/bin/node or /opt/homebrew/bin/node

その後、Claude Desktop を再起動します。

---

使い方

ブリッジは Claude Desktop の起動時に自動的に開始されます。
Safari は、拡張機能を有効にした状態で開いておく必要があります。

拡張機能は、スリープ後や Safari の設定画面を開いた後に、手動操作なしでブリッジへ自動的に再接続します。

Safari プロファイル

Safari の各プロファイルでは、拡張機能がそれぞれ独立して動作します。拡張機能のツールバーポップアップで、それぞれに名前を付けてください（Profile name）。名前のないプロファイルはすべて default として登録されるため、Claude は区別できません。名前は大文字と小文字を区別せずに照合されます（dev は Dev に一致します）。

すべてのツールは profile 引数を受け取ります。プロファイルが指定されていない場合に Claude が特定のプロファイルを使うようにするには、サーバーエントリーで SAFARI_DEFAULT_PROFILE を設定してください。個人用プロファイルのセッションや Cookie を使ってブラウジングしないよう、Claude 専用のプロファイルを使うことをおすすめします。

"safari": {
  "command": "node",
  "args": ["/absolute/path/to/claudeForSafari/bridge/bridge.js"],
  "env": { "SAFARI_DEFAULT_PROFILE": "Dev" }
}

そのプロファイルが接続されていない場合、ツールは別のプロファイルにフォールバックせず、明示的なエラーを返します。SAFARI_DEFAULT_PROFILE を設定しない場合は、従来どおり、最初に接続されたプロファイルが使われます。

---

利用可能なツール（13）

ツール	説明
safari_list_profiles	利用可能な Safari プロファイルを一覧表示する
safari_navigate	URL に移動する
safari_get_page_text	現在のページの表示テキストを読み取る
safari_read_page	現在のページの HTML 全体を取得する
safari_javascript	任意の JavaScript を実行する
safari_find	CSS セレクターまたはテキスト内容で要素を検索する
safari_click	要素をクリックする
safari_form_input	<input> または <textarea> フィールドに入力する
safari_scroll	ページをスクロールする
safari_tabs_list	開いているタブを一覧表示する
safari_tabs_create	新しいタブを開く
safari_tabs_close	タブを閉じる
safari_tabs_switch	ID でタブを切り替える

safari_form_input は <input> および <textarea> フィールドに対応しています。contenteditable を使用するリッチテキストエディター（Notion、Gmail の作成画面など）には、まだ対応していません。

---

トラブルシューティング

「Safari 拡張機能が接続されていません」

• Safari は起動していますか？Safari → 拡張機能で拡張機能が有効になっていますか？Safari プロファイルを使用している場合は、設定 → プロファイル → お使いのプロファイル → 拡張機能でも有効になっていますか？
• ブリッジが実行中か確認してください：ps aux | grep bridge.js
• ブリッジのログ（Claude Desktop によって書き込まれます）：~/Library/Logs/Claude/mcp-server-safari.log — 各行は [claude-safari] で始まり、接続拒否とプロファイル登録が記録されます。
• 拡張機能のログ：Safari → 開発 → Web Extension Background Content → Claude for Safari（設定 → 詳細で「開発」メニューを有効にしてください）。

スクリプトの挿入がアクセス拒否になる場合
→ Safari → 設定 → 拡張機能 → claudeExtension → すべての Web サイトで許可

safari_get_page_text が内部タブで失敗する場合
→ Safari の内部ページ（favorites://、about:blank など）にはスクリプトを挿入できません。先に http:// または https:// の URL に移動してください。

ブリッジが起動しない場合
→ Node.js を確認してください：node -v（v20 以降が必要です）
→ claude_desktop_config.json では node の絶対パスを使用してください

Xcode — 「署名証明書がありません」
→ Xcode → 設定 → アカウント → Apple ID を追加 → 手動プロファイルをダウンロード

---

セキュリティモデル

ブリッジは ws://localhost:45678 でリッスンし、ループバックアドレス（::1 と 127.0.0.1）のみにバインドされます。そのため、ネットワーク経由では到達できません。

Web ページからの接続は拒否されます。 ページが WebSocket を開くと、ブラウザーは常に Origin ヘッダーを送信し、ページ側でこれを偽装することはできません。ブリッジが受け入れるのは Safari 拡張機能のオリジン（safari-web-extension://…）のみです。それ以外のオリジンからの接続には 403 Forbidden が返され、ブリッジのログに記録されます。

応答は、コマンドの送信先と同じソケットからのものだけが受け入れられます。 また、コマンド ID はランダムなため、別のクライアントが拡張機能の代わりに応答することはできません。

safari_find がパスワードフィールドの値を返すことはありません（フィールドに値が入力されている場合は <redacted> と報告します）。

保護されないもの — ブリッジと拡張機能の間に暗号化認証はありません。そのため、脅威モデルでは次のことを前提としています。

• ユーザーアカウントで実行中の他のプロセスは信頼できる — Origin ヘッダーを持たないクライアント（Claude Desktop が起動するリレーブリッジなど）は受け入れられます。
• インストール済みの他の Safari 拡張機能は信頼できる — それらは safari-web-extension:// スキームを共有します。

safari_javascript はアクティブなタブで任意の JavaScript を実行し、safari_read_page は設計上、ページの HTML 全体を返します。ブラウザーの DevTools と同様に扱い、信頼できるページでのみ使用してください。

1.2.x からの更新： 更新を取得した後、Claude Desktop を完全に終了（Cmd+Q）してください。これにより、以前のバージョンのブリッジがポートでリッスンし続けるのを防げます。

開発

拡張機能のファイルはすべて、次の場所で編集してください。

app/claudeExtension Extension/Resources/

background.js または manifest.json を編集した後：

1. Xcode で再ビルドします（Cmd+R）
2. Safari を終了（Cmd+Q）して再起動します — 設定で拡張機能を無効にしてから再度有効にするだけでは、現在のプロファイル内で再読み込みされるだけです。

1 つのチェックアウトからビルドしてください。2 つ目のフォルダー（別のクローン、ワークツリー、xcodebuild -derivedDataPath …）からプロジェクトをビルドすると、拡張機能のコピーがもう 1 つ登録され、Safari は最初のものと並行して読み込みます。pluginkit -mAvvv -i com.wilfrid.B.claudeExtension.Extension で登録済みのコピーを一覧表示できます。

ブリッジ（bridge/bridge.js）は再ビルドする必要はありません。Claude Desktop を次回再起動した際に、Node.js が変更を読み込みます。

テスト

cd bridge
npm ci
npm test

テストでは、ブリッジをテスト専用のポート（Claude Desktop を引き続き実行できるよう、45678 は使用しません）で複製して実行し、偽のブラウザー API を使ったサンドボックス内で background.js を実行します。所要時間は約30秒です。実際の再接続と猶予時間の遅延をテストします。マシンにテストから到達可能な LAN アドレスがない場合は、理由を表示してネットワークテストをスキップします。GitHub Actions では、すべてのプルリクエストでテストが実行されます。

実際の Safari でのみ確認できる項目 — エクステンションを再ビルドし、Safari を再起動した後に確認します。

1. バージョン — テスト用のタブで safari_javascript を使い、return browser.runtime.getManifest().version を実行すると、ビルドしたバージョンが返されます。
2. オリジン — ブリッジのログ（~/Library/Logs/Claude/mcp-server-safari.log）に Profile "…" connected (origin safari-web-extension://…) と表示されます。
3. ツール — フォームのあるページで safari_tabs_create、safari_find、safari_click、safari_form_input、safari_scroll、safari_tabs_close を実行し、ページ上で動作を確認します。
4. Web ページからの接続拒否 — 通常の http で配信されているページから ws://localhost:45678 を開くとエラーが発生し、ブリッジのログに Refused connection from origin "http://…" と表示されます。
5. ホストアプリ — claudeExtension.app を開くと、エクステンションの状態が表示されます。そのボタンをクリックするとアプリが終了し、Safari の設定が開きます。

---

ライセンス

MIT