Safari MCP Server 怎么配置：让 Agent 直接调试 Safari 页面

Safari 27 beta / Technology Preview 提供官方 MCP Server，Agent 可读 DOM、网络、截图与控制台。本文给出 safaridriver 配置步骤、Claude/Codex 命令，以及适用场景与隐私边界。

Safari MCP Server 怎么配置：让 Agent 直接调试 Safari 页面

WebKit 团队为 Safari 27 beta 与 Safari Technology Preview 引入了官方 Safari MCP Server：把真实 Safari 窗口接到 MCP 客户端后，Agent 能自己看渲染结果、网络请求、控制台和截图，少做一轮「你截图 → 我猜 → 你再试」。中文侧目前几乎只有新闻摘要，缺可复制配置——下面按官方步骤落地。

它解决什么问题

传统调试是「浏览器 ↔ 编辑器」来回跳。接上 Safari MCP 后，Agent 可以：

  • 在 Safari 里打开页面，检查兼容性与布局
  • 读 console、网络详情，定位慢请求
  • 跑页面内 JS，看 navigation timing 等指标
  • 做基础无障碍检查（缺 label、ARIA、对比度等）
  • 模拟点击、输入、滚动，验证表单/结账等状态

前提是：你的客户端支持 MCP（Claude Code、Codex、Cursor 等），且本机跑的是带 MCP 的 Safari 渠道（beta / STP），不是任意旧版正式版。Windows / Linux 用户目前无法用此方案——Safari MCP 绑定 macOS + WebKit 渠道。

前置：打开开发者与远程自动化

Safari 27 beta：

  1. 从 Apple Developer 或 TestFlight 安装 Safari 27 beta。
  2. Safari → Settings → Advanced → 勾选 Show features for web developers。
  3. Safari → Settings → Developer → 勾选 Allow remote automation and external agents。

Safari Technology Preview：

  1. 安装 STP（与系统 Safari 可并存）。
  2. 同样打开 web developer features。
  3. Developer 里启用 remote automation and external agents。

未勾选时，safaridriver --mcp 往往起不来或 Agent 连不上——先查这两项，再查 MCP 配置。改完设置建议完全退出 Safari 再开，避免旧进程没吃到新开关。

Claude Code / Codex 一条命令接入

官方示例（路径以本机为准）：

# Safari 27 beta
claude mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp
codex mcp add safari-mcp -- "/usr/bin/safaridriver" --mcp

# Safari Technology Preview
claude mcp add safari-mcp-stp -- \
  "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp
codex mcp add safari-mcp-stp -- \
  "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp

其它 MCP 客户端可在 mcp.json 写：

{
  "mcpServers": {
    "safari-mcp": {
      "command": "/usr/bin/safaridriver",
      "args": ["--mcp"]
    }
  }
}

Cursor 用户：在项目或全局 .cursor/mcp.json 写入同上结构，保存后 Cursor → Settings → MCP 里确认 server 为绿色，必要时重启窗口。多项目共用时可放 ~/.cursor/mcp.json。

接好后不必每次念「请用 Safari MCP」；用自然语言即可，例如：

Find bugs on my site in Safari
How accessible is my site in Safari?
See how my website performs in Safari

MCP 能力全景与工作流变化见 MCP 与 Claude Code：2026 工作流转变；工具描述写差会导致 Agent 选错工具，见下一篇生态问题讨论时可对照 Claude Code / Cursor 接 MCP 能做什么。

配完怎么验证（三步）

  1. 终端："/usr/bin/safaridriver" --mcp 或 STP 路径加 --mcp，进程应挂起等待 stdio，不应立刻报错退出。
  2. 客户端：在 Claude Code / Cursor 里问「列出当前 Safari 标签页」或「打开 http://localhost:3000 并截图」。
  3. Safari 窗口：应出现新标签或导航；Agent 返回的截图/控制台应与肉眼一致。

若第 1 步就失败，99% 是 Developer 开关或 safaridriver 路径错（beta 与 STP 不要混用同一条配置）。

常用工具能力一览（选型用）

工具方向 例子 用途
页面观察 screenshot / get_page_content / page_info 看渲染与文案
调试 browser_console_messages / list_network_requests 报错与慢请求
交互 page_interactions / navigate_to_url / create_tab 复现用户路径
度量 evaluate_javascript 性能/自定义探测
环境 set_viewport_size / set_emulated_media 响应式与 print

Agent 能自己发现「Safari 特有布局坏了」，比你口头描述 CSS 更稳。仍建议你对合并结果做人工验收——MCP 降低信息差，不替代产品判断。测 iOS Safari 行为时，Safari MCP 只能代表 macOS WebKit，真机仍需 Xcode Simulator 或设备。

故障排查速查

症状 优先检查
MCP server 红 / 连不上 Developer → remote automation 是否勾选
safaridriver: command not found 用 STP 完整路径，或确认 beta 已装
Agent 说没有 Safari 工具 客户端 MCP 缓存；重启 IDE / claude mcp list
本地 3000 打不开 dev server 是否监听；Safari 是否拦 mixed content
截图空白 页面未 load 完；让 Agent 先 page_info 再截
同时开 beta 与 STP 两个 server 用不同 name，避免抢同一个 driver

国内开发者常见卡点：只有 Mac 能玩；公司机若锁 TestFlight / 外网，需走 STP 或内测包分发。页面若依赖 Google Fonts / 境外 CDN，Safari 里加载慢会被 Agent 误判为性能问题——本地调试可换国内镜像或 mock。

典型工作流示例

Safari 兼容排查（适合接在本地 dev 之后）：

  1. 启动 pnpm dev，确认 localhost:3000 在 Chrome 正常
  2. 让 Agent：「用 Safari MCP 打开同一 URL，对比 flex 布局与 font-size」
  3. 若 console 有 -webkit- 相关警告，让 Agent 列出差异 DOM 节点
  4. 你改 CSS，Agent 再截图对比——比手动双开窗口少一轮描述成本

性能粗测（非 Lighthouse 替代）：

  1. Agent 执行 evaluate_javascript 读 performance.timing 或 Navigation Timing API
  2. 结合 list_network_requests 找 >500ms 的资源
  3. 人决定是 CDN、接口还是 bundle 体积问题

注意：Agent 点的路径不等于真实用户分布；结账、OAuth 等仍要人工走一遍。

与 Claude Code / Cursor 并存其它 MCP

Safari MCP 常与 filesystem、GitHub MCP 同开。为避免工具名冲突：

  • 给 server 起名带前缀，如 safari-mcp 而非 browser
  • 系统提示里写清：「Safari 兼容任务用 safari-mcp，CI 回归用 Playwright」
  • 上下文紧张时临时 claude mcp remove 关掉不用的 server

多 MCP 并存时的 token 与选型问题，见 Claude Code 上下文窗口管理 里的「工具目录膨胀」一节。

版本与渠道选择建议

你的情况 建议渠道
要跟 macOS 下一版 Safari 行为对齐 Safari 27 beta
日常开发还要稳定浏览 STP（与系统 Safari 并存）
公司禁 beta 等 STP 或正式版公告，别硬配旧 Safari
需要测 iOS 独有 bug MCP 不够，补 Simulator / 真机

beta 与 STP 的 safaridriver 路径不同，换渠道时要改 MCP 配置并重启客户端。同一台机器可以同时注册 safari-mcp 与 safari-mcp-stp，按任务指定即可。

本地 HTTPS（mkcert）站点在 Safari 里若报证书不受信任，Agent 的 navigate_to_url 也会失败——先在 Safari 人工信任一次，或在 dev 环境用 HTTP 做 MCP 调试，别在 Agent 循环里反复撞证书墙。

测内网页面时，确认 dev server 绑定 0.0.0.0 而非仅 127.0.0.1，否则 Safari 与 Agent 对「本机」的解析偶尔不一致；统一用 localhost 或局域网 IP 可减少误判。

隐私与信任边界

官方明确：Safari MCP 在本机运行，自身不主动外联；页面内容、截图、控制台会交给你连接的那个 Agent/模型。它读不到你 Safari 里 AutoFill 等个人资料那一类数据，但一旦内容进了 Agent，后续如何处理取决于该模型供应商。

实务建议：

  • 只接你信任的本地/企业 Agent
  • 别在含生产密钥的已登录会话里随手让 Agent「随便点」
  • 团队共享机上，远程自动化开关按需开，测完可关
  • 截图可能含内部 URL、用户信息，别贴到公共 issue

常见问题

正式版 Safari 能用吗？

以 WebKit 公告为准：能力随 Safari 27 beta 与 STP 推出。稳定版是否跟进要看后续发布说明，不要假设「现在所有 macOS Safari 都能 --mcp」。发版前用 STP 扫一遍兼容，比赌正式版行为更稳。

Cursor 怎么配？

把上面的 command/args 写进 Cursor 的 MCP 配置即可（字段名随版本可能是 mcpServers）。配完重启 MCP / 重载窗口，用「在 Safari 打开本地 3000 并截图」验证。Team 版若走集中 MCP 分发，参考团队 marketplace 文档把 safaridriver 路径写成绝对路径。

和 Playwright MCP 比怎么选？

Playwright 偏跨浏览器自动化与 CI；Safari MCP 偏真实 Safari 引擎 + 开发中调试闭环。做 Safari 兼容与 WebKit 特有问题，优先官方 Safari MCP；回归套件仍可留给 Playwright。两者可同时装，用不同 server 名，按任务指定浏览器。

参考资料