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 scheme（宿主应用）
3. 选择 My Mac 作为目标设备
4. 按 Cmd+R — Xcode 将构建并启动应用

macOS 会显示横幅：“claudeExtension 想要添加 Safari 扩展” → 点击 打开 Safari 设置并启用扩展。

步骤 4 — 在 Safari 中启用扩展

1. Safari → 设置（Cmd+,） → 扩展标签页
2. 勾选 claudeExtension
3. 在右侧栏中 → 允许在所有网站上使用

若未授予此权限，向页面注入脚本会静默失败。

步骤 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 配置文件都会运行自己的扩展副本。请在扩展工具栏弹出窗口中为每个配置文件命名（配置文件名称）；未命名的配置文件都会注册为 default，Claude 将无法区分它们。名称匹配时不区分大小写（dev 与 Dev 匹配）。

每个工具都接受 profile 参数。若希望 Claude 在未指定名称时使用某个配置文件——建议使用一个专供 Claude 使用的配置文件，以免它使用你个人配置文件中的会话和 Cookie 浏览——请在服务条目中设置 SAFARI_DEFAULT_PROFILE：

"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 扩展后台内容 → Claude for Safari（在“设置” →“高级”中启用“开发”菜单）。

脚本注入时权限被拒绝
→ Safari → 设置 → 扩展 → claudeExtension → 允许访问所有网站

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）：网络无法访问它。

网页连接会被拒绝。 网页打开 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，这是设计如此。请像使用浏览器开发者工具一样谨慎对待它们 — 只在你信任的页面上使用。

从 1.2.x 更新： 拉取代码后，请完全退出 Claude Desktop（Cmd+Q），以免旧版本的桥接继续侦听该端口。

开发

所有扩展文件都应在此处编辑：

app/claudeExtension Extension/Resources/

编辑 background.js 或 manifest.json 后：

1. 在 Xcode 中重新构建（Cmd+R）
2. 退出 Safari（Cmd+Q）并重新打开 — 在“设置”中停用再重新启用扩展，只会在当前配置文件中重新加载扩展。

从单个检出目录构建：从第二个文件夹（另一个克隆、副本工作树、xcodebuild -derivedDataPath …）构建项目，会注册扩展的第二个副本，Safari 随后会同时加载两个副本。pluginkit -mAvvv -i com.wilfrid.B.claudeExtension.Extension 会列出已注册的副本。

桥接（bridge/bridge.js）无需重新构建 — Claude Desktop 下次重启时，Node.js 会加载更改。

测试

cd bridge
npm ci
npm test

测试会在各自的端口上运行桥接程序副本（绝不会使用 45678，因此 Claude Desktop 可以继续运行），并在沙盒中运行带有模拟浏览器 API 的 background.js。测试大约需要 30 秒：会实际测试重新连接和宽限延迟。如果机器没有测试可访问的局域网地址，则会跳过网络测试，并显示原因。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. 拒绝网页连接 — 通过纯 http 提供服务的页面若尝试打开 ws://localhost:45678，会收到错误，且桥接程序日志会显示 Refused connection from origin "http://…"。
5. 宿主应用 — 打开 claudeExtension.app 会显示扩展的状态；其按钮会退出应用并打开 Safari 设置。

---

许可证

MIT