Safari MCP

🦁 Safari MCP

为编码 Agent 打造的浏览器。

你自己的 Safari，已登录——不用 Chrome，不发热，也不使用无头模式。

在 VS Code 中安装 · VS Code Insiders · 在 Cursor 中安装

98 个工具 · 无需 Chrome/Puppeteer/Playwright · 每条命令约 5 毫秒 · 比 Chrome 少占用 60% CPU

快速开始 · 全部 98 个工具 · 示例 · 为什么选择 Safari MCP？ · 架构 · 更新日志

❌ 不使用 Safari MCP

你的 AI Agent 需要浏览网页，因此它只能：

• 通过 Playwright 启动 Chromium——没有登录信息、Cookie 或会话
• 使用 Chrome DevTools MCP——再运行一个浏览器，让风扇全速运转
• 依赖无头爬虫——被 Cloudflare、reCAPTCHA 和机器人检测拦截

✅ 使用 Safari MCP

你的 AI 可以操控你已登录的 Safari——Gmail、GitHub、Ahrefs、Slack、网银。

原生 WebKit。CPU 占用降低约 60%。后台运行。98 个工具。一条 npx 命令。仅限 macOS。

📰 freeCodeCamp 专题报道：如何在 macOS 上将 AI 编码 Agent 连接到浏览器 · HackerNoon：逆向分析 React、Shadow DOM 和 CSP

🍎 Apple 推出了官方 Safari MCP——safaridriver --mcp，于 Safari Technology Preview 247（2026 年 7 月）首次推出，并已包含在稳定版 Safari 27.0 中。它通过隔离的自动化会话执行调试操作。safari-mcp 操控的是你已登录的真实 Safari——使用你的 Cookie 和会话，在后台运行，并提供 98 个工具。完整对比请见下文。

亮点

• 98 个工具——导航、点击、表单、截图、网络、存储、无障碍等
• 不发热——在 Apple Silicon 上运行原生 WebKit，CPU 占用比 Chrome 低约 60%
• 你自己的浏览器——保留所有登录信息、Cookie 和会话（Gmail、GitHub、Ahrefs 等）
• 后台运行——Safari 始终在后台，不会抢占窗口焦点
• 无需浏览器依赖——无需 Puppeteer、Playwright、WebDriver 或 Chrome
• 持久进程——复用单个 osascript 进程（每条命令约 5 毫秒，而非约 80 毫秒）
• 兼容框架——通过原生 setter 填充 React、Vue、Angular 和 Svelte 表单

用户自己的评价

并非征集的推荐语——这些引言摘自公开问题跟踪器，每条都链接到对应的讨论串。

“我会在正常使用的 Safari 配置中并行运行多个 Pi 会话/子 Agent。有意共享 Cookie 和登录状态。” — @maxim，谈在真实浏览器中运行并发 Agent

“该服务采用了刻意设计的标签页所有权模型……代码对此处理得很谨慎，对于默认情况来说，这是正确的安全姿态。” — @turner-moore，谈这些防护为何拒绝操作你的标签页

“直接从软件包进行本地验证：Safari MCP doctor 6/6。” — @jrepp，发现并修复了焦点辅助工具中的队列对齐错误

快速开始

前置条件

• macOS（任何支持 Safari 的版本）
• Node.js 20+
• Safari → 设置 → 高级 → 显示网页开发者功能 ✓
• Safari → 设置 → 开发者 → 允许来自 Apple Events 的 JavaScript ✓

安装（一个命令）

npx safari-mcp

就这么简单——无需全局安装。或者永久安装：

npm install -g safari-mcp

配置 MCP 客户端

所有客户端都以相同的方式运行 Safari MCP——npx safari-mcp。选择你的编辑器：

claude mcp add safari -- npx safari-mcp

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

{
  "servers": {
    "safari": {
      "type": "stdio",
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

mcpServers:
  - name: safari
    command: npx
    args:
      - safari-mcp

extensions:
  safari:
    name: safari
    type: stdio
    cmd: npx
    args:
      - safari-mcp
    enabled: true

{
  "context_servers": {
    "safari": {
      "command": {
        "path": "npx",
        "args": ["safari-mcp"]
      }
    }
  }
}

brew install achiya-automation/tap/safari-mcp

git clone https://github.com/achiya-automation/safari-mcp.git
cd safari-mcp && npm install

使用工作流

AI Agent 使用 Safari MCP 时推荐采用以下模式：

1. safari_snapshot        → Get page state (accessibility tree)
2. safari_click/fill/...  → Interact with elements by ref
3. safari_snapshot        → Verify the result

元素定位——工具支持多种定位策略：

提示： 先使用 safari_snapshot 获取元素引用，再用引用进行精确定位。这样比 CSS 选择器更快、更可靠。

同时运行多个 Agent

多个 Agent 或子 Agent 同时操控一个 Safari 时，会争抢当前活动标签页——除非让它们连接到共享 HTTP 守护进程，而不是每个客户端各运行一个进程：

SAFARI_MCP_HTTP=1 SAFARI_MCP_HTTP_PORT=9225 npx safari-mcp

然后让每个客户端都连接到它：

{ "mcpServers": { "safari-mcp": { "type": "http", "url": "http://127.0.0.1:9225/mcp" } } }

一个守护进程，多个会话——每个会话都有自己的标签页状态。服务器根据 MCP 会话 ID，为 activeTabIndex、所有权标记和唯一标签页标记设置键，因此会话 A 无法读取或操控会话 B 的标签页。

有两个特性让这种方式真正安全，而不只是整洁：

• 标签页身份由标记确定，而非索引。 每个会话都会在自己打开的页面中写入唯一 ID，因此即使发生导航，或者用户重新排序或关闭其他标签页，所有权也能保持不变。单靠索引会悄无声息地指向错误的标签页。

• 出错时会安全拒绝操作。 如果无法重新找到会话标记的标签页，每个工具都会拒绝操作，而不会退回到当前最前面的标签页——因为那通常是你的标签页：

  Tab tracking lost — refusing to fall back to "current tab of window"
  (would target the user's active tab). Call safari_new_tab to reopen.
  

这也大幅减少了进程数量：17 个并发会话原本需要约 17 个 node 进程，现在只需 1 个。

SAFARI_PROFILE 仍为可选项——不设置时，会话会使用你常规的 Safari 窗口、Cookie 和登录状态。docs/http-transport-design.md 中有详细说明。

更喜欢使用 stdio（每个 Agent 一个进程），而不是持久守护进程？也可以——此时隔离由进程边界本身提供。需要注意的是：如果客户端通过 mcporter 复用多个 Agent，mcporter 会为所有 Agent 缓存同一个 MCP 客户端——无论你选择哪种传输方式——因此服务器无法看到不同的会话，也无法启用按会话隔离。mcporter-lanes（由 @maxim 开发的 pi 扩展，源于 #76）在上游解决了这个问题：每个 Agent 会话都有自己的守护进程目录——因此也有自己的 safari-mcp——并设有空闲超时，避免进程不断累积。

操作已打开的标签页

默认情况下，服务器只会操作自己打开的标签页。如果让它操作你打开的标签页，它会拒绝：

Tab safety: refusing "click" — current tab (https://mail.example.com/inbox) was not
opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.

设置这个默认行为，是因为早期版本确实会点开并关闭用户的标签页。但“阅读我正在看的文章”和“填写我屏幕上的表单”都是实际需求，而且重新打开页面会丢失当前标签页中有用的会话状态。设置 SAFARI_MCP_ALLOW_USER_TABS=1 后，明确调用 safari_switch_tab 就会接管指定的标签页，而不是拒绝操作；此后会话便能像操作自己打开的标签页一样操作它，并会明确说明：

{ "tabIndex": 3, "safeUrl": "https://mail.example.com/inbox", "note": "(user tab, opted-in)" }

这个标记有意不会改变以下行为：

• 它允许接管标签页，但不会解除防护。 只有 safari_switch_tab 可以接管，而且只能接管你指定的标签页。普通点击或导航仍不会跳转到碰巧处于最前面的标签页——服务器操作的是你指定的标签页，而不是你切换到的那个。
• safari_close_tab 仍会拒绝操作。 关闭是唯一无法撤销的操作，因此被接管的标签页可以修改，但不会被关闭。请自行关闭。
• 接管仅限当前会话。 共享所有权文件中不会写入任何信息，因此接管会随着会话结束，不会泄漏到这台机器上的下一个进程。

safari_doctor 会显示该标记的状态，对被接管标签页的每次操作都会记录 (user tab, opted-in)——这样“它为什么操作我的标签页”就有据可查，不再是个谜。默认关闭；仅为你希望在自己的浏览会话中工作的 Agent 启用。设计详见 #92。

环境变量

SAFARI_MCP_RAISE_ON_NAVIGATE=1 适用于主要目的在于向你展示网页的 Agent，例如回答“打开 YouTube”的语音助手或演示驱动程序。其他情况都应关闭此选项：默认情况下，Safari MCP 会在后台运行，并将焦点交还给你正在使用的应用，因此 Agent 可以操作网页，而你可以继续在其他地方输入。

工具（98 个）

安全性

Safari MCP 在你的 Mac 本地运行，攻击面极小：

Safari MCP 与替代方案

提示： 日常浏览任务（95% 的工作）使用 Safari MCP，仅在进行 Lighthouse/Performance 审计时使用 Chrome DevTools MCP。

与 Apple 官方 Safari MCP（safaridriver）的比较

2026 年 7 月，Apple 发布了基于 safaridriver 构建的官方 Safari MCP 服务——先是在 Safari Technology Preview 247 中，之后在稳定版 Safari 27.0 中推出。这充分验证了这一类别的价值——但它针对的是另一种用途。Apple 的服务驱动的是用于调试的隔离 WebDriver 自动化会话；safari-mcp 驱动的是你已登录的真实 Safari。

在 macOS 27.0 和 Safari 27.0 上，safaridriver --help 会列出 --mcp，其 tools/list 返回 17 个条目（已于 2026-09-15 验证）；Safari 26.5.2 没有 --mcp（已于 2026-07-23 验证）。可用 safaridriver --help | grep mcp 检查你自己的设备。

同时运行两者？ Apple 的设置指南会将其服务注册为 safari-mcp（claude mcp add safari-mcp -- /usr/bin/safaridriver --mcp）——与此软件包同名。请为其中一个使用其他名称，例如 claude mcp add safari-webdriver -- /usr/bin/safaridriver --mcp，以免客户端用一个覆盖另一个，或让你无法分辨是哪个服务作出了响应。

关于 navigator.webdriver 这一行： WebDriver 标准要求每个远程控制的会话都报告 true，因此 Apple 的服务会这样做。safari-mcp 在普通标签页中执行 JavaScript，因此读取到的是 false（已在 Safari 27.0 上于 2026-09-17 验证）。如果某个网站拒绝 WebDriver 流量，这就是两者的区别。这并不是反检测功能——浏览器的其他方面都没有伪装，而且使用的是真实登录信息，因此请假设每个页面都清楚地知道你的身份。

适合选择 Apple 服务的情况： 你明确需要一个干净隔离、符合 WebDriver 标准的会话，以便在 Safari 27 或更高版本上进行兼容性调试。其他所有情况——在你已登录的浏览器上进行日常后台自动化——safari-mcp 正是为此而构建的。

为什么选择 Safari MCP，而不是其他 Safari MCP 项目？

目前有几个名为 “safari-mcp” 的项目。下面是它们的对比：

简而言之——如果你想要功能最全面、安装最顺畅、工具最多且积极维护的 Safari MCP，选这个就对了。

架构

Safari MCP 采用双引擎架构——优先使用扩展，以获得更快速度和高级功能；同时将 AppleScript 作为始终可用的备用方案：

Claude/Cursor/AI Agent
        ↓ MCP Protocol (stdio)
   Safari MCP Server (Node.js)
        ↓                    ↓
   Extension (HTTP)     AppleScript + Swift daemon
   (~5-20ms/cmd)        (~5ms/cmd, always available)
        ↓                    ↓
   Content Script       do JavaScript in tab N
        ↓                    ↓
   Page DOM ←←←←←←←←←← Page DOM

关键设计决策：

• 带自动回退的双引擎——优先使用扩展；如果未连接，则由 AppleScript 无缝处理所有操作
• 持久运行的 Swift 辅助程序——使用一个长期运行的进程，而不是为每条命令启动新进程（速度快 16 倍）
• 按标签页索引执行操作——所有 JS 都在指定索引的标签页上运行，绝不抢占视觉焦点
• 优先使用 JS——输入、点击和文件上传都使用 JavaScript 事件（不会与 System Events 的键盘操作冲突）
• 不调用 activate——Safari 永远不会被置于前台

Safari 扩展（可选）

Safari MCP 扩展可选但推荐安装。不安装扩展时，仍可单独通过 AppleScript 使用约 80% 的功能。扩展提供了 AppleScript 无法实现的能力：

扩展新增功能

什么时候需要扩展？ 如果你要自动化操作使用封闭式 Shadow DOM 的现代 SPA（例如 Reddit）、采用严格内容安全策略的网站，或大量依赖框架的编辑器（Draft.js、ProseMirror、Slate），就需要扩展。

安装扩展

该扩展需要使用 Xcode（免费，随 macOS 提供）进行一次性构建。

npm 用户须知： npm 软件包中不包含 xcode/ 目录。 请克隆 GitHub 仓库以从源代码构建。

前置条件： Xcode（从 App Store 安装，免费）

# 1. Clone the repo (the npm package does not include the Xcode project)
git clone https://github.com/achiya-automation/safari-mcp.git
cd safari-mcp

# 2. Build a clean, Apple Development-signed app
# If needed, first choose your Team in Xcode → Signing & Capabilities.
xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
  -scheme "Safari MCP (macOS)" -configuration Release \
  -allowProvisioningUpdates clean build

# 3. Locate the signed app
APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release -name "Safari MCP.app" -maxdepth 2 | head -1)

# 4. Re-sign safari-helper with the Apple Events entitlement
# (helps macOS surface the TCC Automation prompt reliably).
# Keep the stable identifier: macOS keys the Accessibility grant to it.
codesign --sign - --force --identifier com.achiya-automation.safari-mcp \
  --entitlements safari-helper.entitlements safari-helper

# 5. Open the app (needed once so Safari registers the extension)
open "$APP_PATH"

请勿使用 codesign --deep --sign - 对 Safari MCP.app 进行临时重签名。 这会替换封装应用和内嵌扩展上的 Apple Development 身份；当前版本的 Safari 可能会因此静默停用扩展或将其标记为已移除。如果先前的构建曾进行临时签名，请再次运行上面的 clean build 命令。

也可以直接在 Xcode 中打开 xcode/Safari MCP/Safari MCP.xcodeproj，在“Signing & Capabilities”下选择你的 Apple ID，然后点击 Run。免费的个人 Apple Developer 帐户足以满足本地使用需求。

然后在 Safari 中：

1. Safari → 设置 → 高级 → 启用 显示网页开发者功能
2. Safari → 设置 → 开发 → 允许未签名的扩展（每次重启 Safari 后都需要启用）
3. Safari → 设置 → 扩展 → 启用 Safari MCP Bridge

扩展会自动连接到第一个声明的 Safari 配置文件与自身匹配的本地桥接服务。默认桥接端口为 9224、9228、9232 和 9236；单配置文件设置通常使用 9224。

注意： 每次 Safari 重启后，“允许未签名的扩展”都会重置。你需要在每次重启后前往 Safari → 设置 → 开发重新启用该选项。扩展本身仍会保持安装状态。

工具栏图标状态：

• ON — 已连接到 MCP 服务
• OFF — 已通过弹出窗口手动停用
• （无徽标） — 服务未运行，将自动重新连接

macOS 权限

Safari MCP 需要以下一次性权限：

授予 safari-helper 辅助功能权限（运行 safari_native_* 所必需）

safari_native_click、safari_native_keyboard 和 safari_native_hover 工具会向 Safari 注入操作系统级别的 CGEvent 事件，而不会抢占焦点。macOS 要求先在辅助功能中批准底层 helper 二进制文件，这些事件才能发送到非前台窗口。

1. 打开系统设置 → 隐私与安全性 → 辅助功能（在 macOS 27 中，该面板名为设备控制与数据访问）。
2. 点击 +（如有需要，请使用密码解锁）。
3. 找到 helper 二进制文件并添加：
   • npm 全局安装：$(npm root -g)/safari-mcp/safari-helper
   • npx / 项目安装：./node_modules/safari-mcp/safari-helper
   • 从源代码克隆：/path/to/safari-mcp/safari-helper
4. 确保其旁边的开关处于 ON 状态。

postinstall 脚本会使用稳定标识符（com.achiya-automation.safari-mcp）重新签署 helper，使此权限在后续升级后仍然有效——如果没有这一步，每次 npm update 都会静默撤销批准，因为二进制文件的临时签名标识符会随每次构建而改变。

如果 safari_native_click 报告成功，但页面没有反应（未触发任何 isTrusted: true 点击事件），helper 很可能尚未获得此批准。safari_*（非 native_）工具不需要此权限。

授予自动化权限 → Safari（IDE 用户须知）

macOS TCC 会将自动化权限授予启动 MCP 服务的父进程，而不是 safari-mcp 本身。因此，你需要向运行 Claude Code / Cursor / Windsurf 的应用授予自动化 → Safari权限——通常是 Visual Studio Code 或 Terminal。

如果权限对话框没有自动出现，请在已获得自动化权限的 Terminal 中运行一次此命令：

osascript -e 'tell application "Safari" to get URL of current tab of window 1'

此调用会将 Terminal 应用注册到自动化数据库中，然后触发 Safari 的权限提示。批准后，后续来自任何子进程链的 MCP 调用都将正常工作。

故障排除

常见问题

适用客户端

Safari MCP 适用于任何兼容 MCP 的客户端：

贡献

欢迎提交 PR！设置说明请参阅 CONTRIBUTING.md。

代码库由两个文件组成：

• safari.js — Safari 自动化层（AppleScript + JavaScript）
• index.js — 含工具定义的 MCP 服务

赞助

Safari MCP 免费且开源。如果它为你节省了时间或 CPU 资源，不妨支持其开发：

你的支持将用于：

• 🧪 在不同 macOS 版本和 Safari 版本上进行测试
• 🛠️ 开发新工具和功能
• 📖 编写文档和示例

成为首位赞助者！

商业支持

需要将 Safari MCP 集成到你的产品或 Agent 技术栈中？ Achiya Automation 可提供：

• 优先修复 Bug，并根据你的使用场景定制开发工具
• 集成咨询 — 将 Safari MCP 接入生产环境中的 Agent 系统（Claude、Cursor、n8n、自定义系统）
• 私有部署支持 — 多用户 Safari MCP、非标准 macOS 环境、CI/CD
• 为采用基于 MCP 的自动化的工程团队提供培训工作坊

由 Safari MCP 的作者打造。开始交流 →

Safari MCP 为 Agent 解锁的能力

当 AI Agent 驱动 Safari MCP 时，它可以实现无头浏览器无法做到的事：

• 真实的已认证会话 — Gmail、GitHub、Ahrefs、Slack、银行控制面板都已登录
• 感知框架的表单填写 — safari_fill_and_submit 原生调用 React/Vue/Angular setter，无需猜测 input 事件是否已触发
• 后台运行 — Agent 可并行工作，同时你继续使用 Mac
• 每个工作流只需调用一次 MCP — safari_run_script 将导航、点击和提取批量处理为一次往返

这种模式适用于各种模型：驱动人类已经信任的浏览器 — 一步即可继承登录状态、Cookie、扩展程序和用户的确切环境。

社区

每月 npm 下载量超过 6,000 次 — 开发者正在 macOS 上使用 Safari MCP 构建 AI Agent。

• GitHub 讨论区 — 提问、分享使用场景
• 问题 — Bug 报告和功能请求
• — 开始参与贡献

生态系统

其他可与 Safari MCP 搭配使用的 macOS MCP 服务：

同时使用 Safari MCP 和 Chrome DevTools MCP？Safari 可处理日常浏览的 95%（零开销），Chrome 则负责需要 Lighthouse 或 Chrome 专属跟踪的 5%。

收录于

许可证

MIT — 随你使用。

由 Achiya Automation 构建 — 为企业提供自动化与 AI Agent。