Skip to content
Back to search

safari-mcp

Native Safari browser automation for AI agents. 98 tools via AppleScript — zero overhead, keeps logins, runs silently in background. Drop-in alternative to Chrome DevTools MCP with 40-60% less CPU/heat on Apple Silicon.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/achiya-automation/safari-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/achiya-automation/safari-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/achiya-automation--safari-mcp/badge.svg)](/listings/achiya-automation--safari-mcp)

HTML

<a href="/listings/achiya-automation--safari-mcp"><img src="/api/listings/achiya-automation--safari-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS (any version with Safari) - Node.js 20+ - Safari → Settings → Advanced → **Show features for web developers** ✓ - Safari → Settings → Developer → **Allow JavaScript from Apple Events** ✓

Install (one command)

npx safari-mcp

That's it — no global install needed. Or install permanently:

npm install -g safari-mcp

Configure your MCP client

All clients run Safari MCP the same way — `npx safari-mcp`. Pick your editor:

<details> <summary><b>Claude Code</b></summary>

claude mcp add safari -- npx safari-mcp

Or edit `~/.mcp.json`:

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

</details>

<details> <summary><b>Claude Desktop</b></summary>

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

Restart Claude Desktop after saving. </details>

<details> <summary><b>Cursor</b></summary>

One-click: [**Install in Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=safari-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D)

Or edit `.cursor/mcp.json` in your project:

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

</details>

<details> <summary><b>VS Code / VS Code Insiders</b></summary>

One-click: [**Install in VS Code**](vscode:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D)

Or edit `.vscode/mcp.json`:

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

</details>

<details> <summary><b>Windsurf</b></summary>

Edit `.windsurf/mcp.json` in your project (or `~/.codeium/windsurf/mcp_config.json` globally):

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

</details>

<details> <summary><b>Cline</b></summary>

Open Cline in VS Code → click the MCP icon → **Edit MCP Settings** → add:

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

</details>

<details> <summary><b>Continue</b></summary>

Edit `~/.continue/config.yaml` (or `.continue/config.yaml` in workspace):

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

</details>

<details> <summary><b>Goose</b></summary>

Edit `~/.config/goose/config.yaml`:

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

</details>

<details> <summary><b>LM Studio</b></summary>

Open LM Studio → **Settings** → **MCP Servers** → **Add Server**:

- **Name:** `safari` - **Command:** `npx` - **Args:** `safari-mcp` </details>

<details> <summary><b>Zed</b></summary>

Open Zed → **Settings** → search for "Context Servers" and add:

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

</details>

<details> <summary><b>Alternative: Homebrew</b></summary>

brew install achiya-automation/tap/safari-mcp

</details>

<details> <summary><b>Alternative: from source</b></summary>

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

</details>

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,037 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="social-preview.png" alt="Safari MCP Server — 98 native browser automation tools for AI agents on macOS" width="100%">
  3. <br/>
  4. # 🦁 Safari MCP
  5. **The browser for your coding agent.**
  6. *Your real Safari, logged in — no Chrome, no heat, no headless.*
  7. [![npm version](https://img.shields.io/npm/v/safari-mcp)](https://www.npmjs.com/package/safari-mcp)
  8. [![npm downloads](https://img.shields.io/npm/dm/safari-mcp)](https://www.npmjs.com/package/safari-mcp)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. [![macOS](https://img.shields.io/badge/macOS-only-blue)](https://www.apple.com/macos/)
  11. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/achiya-automation/safari-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/achiya-automation/safari-mcp)
  12. [Install in VS Code](vscode:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D) ·
  13. [VS Code Insiders](https://insiders.vscode.dev/redirect?url=vscode-insiders:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D) ·
  14. [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=safari-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D)
  15. **98 tools** · **No Chrome/Puppeteer/Playwright needed** · **~5ms per command** · **60% less CPU than Chrome**
  16. [Quick Start](#quick-start) · [All 98 Tools](#tools-98) · [Examples](examples/) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
  17. ![Safari MCP Demo](https://github.com/achiya-automation/safari-mcp/raw/main/assets/safari-mcp-promo.gif)
  18. </div>
  19. ## ❌ Without Safari MCP
  20. Your AI agent needs to browse. So it either:
  21. - **Spins up Chromium via Playwright** — with no logins, no cookies, no sessions
  22. - **Uses Chrome DevTools MCP** — and melts your fan running a second browser
  23. - **Relies on headless scrapers** — blocked by Cloudflare, reCAPTCHA, and bot detection
  24. ## ✅ With Safari MCP
  25. Your AI drives the **Safari you're already logged into** — Gmail, GitHub, Ahrefs, Slack, banking.
  26. Native WebKit. ~60% less CPU. Background operation. 98 tools. One `npx` command. macOS only.
  27. > 📰 **Featured on freeCodeCamp:** [How to Connect Your AI Coding Agent to a Browser on macOS](https://www.freecodecamp.org/news/how-to-connect-your-ai-coding-agent-to-a-browser-on-macos/) · [HackerNoon: Reverse-Engineering React, Shadow DOM, and CSP](https://hackernoon.com/i-had-to-reverse-engineer-react-shadow-dom-and-csp-to-automate-safari-without-chrome)
  28. > 🍎 **Apple ships an official Safari MCP** — `safaridriver --mcp`, first in Safari Technology Preview 247 (July 2026) and in stable Safari since 27.0. It drives an isolated automation session for debugging. safari-mcp drives the **real Safari you're already logged into** — your cookies and sessions, in the background, with 98 tools. See the full comparison below.
  29. ---
  30. ## Highlights
  31. - **98 tools** — navigation, clicks, forms, screenshots, network, storage, accessibility, and more
  32. - **Zero heat** — native WebKit on Apple Silicon, ~60% less CPU than Chrome
  33. - **Your real browser** — keeps all logins, cookies, sessions (Gmail, GitHub, Ahrefs, etc.)
  34. - **Background operation** — Safari stays in the background, no window stealing
  35. - **No browser dependencies** — no Puppeteer, no Playwright, no WebDriver, no Chrome
  36. - **Persistent process** — reuses a single osascript process (~5ms per command vs ~80ms)
  37. - **Framework-compatible** — React, Vue, Angular, Svelte form filling via native setters
  38. ---
  39. ## In users' own words
  40. Not solicited testimonials — quotes lifted from the public issue tracker, each linked to the thread it came from.
  41. > "I run multiple Pi sessions/subagents against my normal Safari profile in parallel. **Sharing its cookies and logins is intentional.**"
  42. > — [@maxim](https://github.com/achiya-automation/safari-mcp/issues/76), on running concurrent agents against a real browser
  43. > "The server has a deliberate tab-ownership model … **the code is careful about this, and for the default case that's the right safety posture.**"
  44. > — [@turner-moore](https://github.com/achiya-automation/safari-mcp/issues/92), on why the guards refuse to touch your tabs
  45. > "Direct local validation from the package: **Safari MCP doctor 6/6.**"
  46. > — [@jrepp](https://github.com/achiya-automation/safari-mcp/pull/53), who found and fixed a queue-alignment bug in the focus helper
  47. ---
  48. ## Quick Start
  49. ### Prerequisites
  50. - macOS (any version with Safari)
  51. - Node.js 20+
  52. - Safari → Settings → Advanced → **Show features for web developers** ✓
  53. - Safari → Settings → Developer → **Allow JavaScript from Apple Events** ✓
  54. ### Install (one command)
  55. ```bash
  56. npx safari-mcp
  57. ```
  58. That's it — no global install needed. Or install permanently:
  59. ```bash
  60. npm install -g safari-mcp
  61. ```
  62. ### Configure your MCP client
  63. All clients run Safari MCP the same way — `npx safari-mcp`. Pick your editor:
  64. <details>
  65. <summary><b>Claude Code</b></summary>
  66. ```bash
  67. claude mcp add safari -- npx safari-mcp
  68. ```
  69. Or edit `~/.mcp.json`:
  70. ```json
  71. {
  72. "mcpServers": {
  73. "safari": {
  74. "command": "npx",
  75. "args": ["safari-mcp"]
  76. }
  77. }
  78. }
  79. ```
  80. </details>
  81. <details>
  82. <summary><b>Claude Desktop</b></summary>
  83. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "safari": {
  88. "command": "npx",
  89. "args": ["safari-mcp"]
  90. }
  91. }
  92. }
  93. ```
  94. Restart Claude Desktop after saving.
  95. </details>
  96. <details>
  97. <summary><b>Cursor</b></summary>
  98. One-click: [**Install in Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=safari-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D)
  99. Or edit `.cursor/mcp.json` in your project:
  100. ```json
  101. {
  102. "mcpServers": {
  103. "safari": {
  104. "command": "npx",
  105. "args": ["safari-mcp"]
  106. }
  107. }
  108. }
  109. ```
  110. </details>
  111. <details>
  112. <summary><b>VS Code / VS Code Insiders</b></summary>
  113. One-click: [**Install in VS Code**](vscode:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D)
  114. Or edit `.vscode/mcp.json`:
  115. ```json
  116. {
  117. "servers": {
  118. "safari": {
  119. "type": "stdio",
  120. "command": "npx",
  121. "args": ["safari-mcp"]
  122. }
  123. }
  124. }
  125. ```
  126. </details>
  127. <details>
  128. <summary><b>Windsurf</b></summary>
  129. Edit `.windsurf/mcp.json` in your project (or `~/.codeium/windsurf/mcp_config.json` globally):
  130. ```json
  131. {
  132. "mcpServers": {
  133. "safari": {
  134. "command": "npx",
  135. "args": ["safari-mcp"]
  136. }
  137. }
  138. }
  139. ```
  140. </details>
  141. <details>
  142. <summary><b>Cline</b></summary>
  143. Open Cline in VS Code → click the MCP icon → **Edit MCP Settings** → add:
  144. ```json
  145. {
  146. "mcpServers": {
  147. "safari": {
  148. "command": "npx",
  149. "args": ["safari-mcp"]
  150. }
  151. }
  152. }
  153. ```
  154. </details>
  155. <details>
  156. <summary><b>Continue</b></summary>
  157. Edit `~/.continue/config.yaml` (or `.continue/config.yaml` in workspace):
  158. ```yaml
  159. mcpServers:
  160. - name: safari
  161. command: npx
  162. args:
  163. - safari-mcp
  164. ```
  165. </details>
  166. <details>
  167. <summary><b>Goose</b></summary>
  168. Edit `~/.config/goose/config.yaml`:
  169. ```yaml
  170. extensions:
  171. safari:
  172. name: safari
  173. type: stdio
  174. cmd: npx
  175. args:
  176. - safari-mcp
  177. enabled: true
  178. ```
  179. </details>
  180. <details>
  181. <summary><b>LM Studio</b></summary>
  182. Open LM Studio → **Settings** → **MCP Servers** → **Add Server**:
  183. - **Name:** `safari`
  184. - **Command:** `npx`
  185. - **Args:** `safari-mcp`
  186. </details>
  187. <details>
  188. <summary><b>Zed</b></summary>
  189. Open Zed → **Settings** → search for "Context Servers" and add:
  190. ```json
  191. {
  192. "context_servers": {
  193. "safari": {
  194. "command": {
  195. "path": "npx",
  196. "args": ["safari-mcp"]
  197. }
  198. }
  199. }
  200. }
  201. ```
  202. </details>
  203. <details>
  204. <summary><b>Alternative: Homebrew</b></summary>
  205. ```bash
  206. brew install achiya-automation/tap/safari-mcp
  207. ```
  208. </details>
  209. <details>
  210. <summary><b>Alternative: from source</b></summary>
  211. ```bash
  212. git clone https://github.com/achiya-automation/safari-mcp.git
  213. cd safari-mcp && npm install
  214. ```
  215. </details>
  216. ---
  217. ## Usage Workflow
  218. The recommended pattern for AI agents using Safari MCP:
  219. ```
  220. 1. safari_snapshot → Get page state (accessibility tree)
  221. 2. safari_click/fill/... → Interact with elements by ref
  222. 3. safari_snapshot → Verify the result
  223. ```
  224. **Element targeting** — tools accept multiple targeting strategies:
  225. | Strategy | Example | Best for |
  226. |----------|---------|----------|
  227. | CSS selector | `#login-btn`, `.submit` | Unique elements |
  228. | Visible text | `"Sign In"`, `"Submit"` | Buttons, links |
  229. | Coordinates | `x: 100, y: 200` | Canvas, custom widgets |
  230. | Ref from snapshot | `ref: "e42"` | Any element from accessibility tree |
  231. > **Tip:** Start with `safari_snapshot` to get element refs, then use refs for precise targeting. This is faster and more reliable than CSS selectors.
  232. After a click or a fill, `safari_snapshot` with `diff: true` returns only the lines that changed since that tab's previous snapshot: `+` lines are new and carry fresh refs, `-` lines are gone. The first call for a tab returns the full snapshot.
  233. ---
  234. ## Running several agents at once
  235. Multiple agents or subagents driving one Safari at the same time will fight over the active tab — unless you run them against a **shared HTTP daemon** instead of one process per client:
  236. ```bash
  237. SAFARI_MCP_HTTP=1 SAFARI_MCP_HTTP_PORT=9225 npx safari-mcp
  238. ```
  239. Then point every client at it:
  240. ```json
  241. { "mcpServers": { "safari-mcp": { "type": "http", "url": "http://127.0.0.1:9225/mcp" } } }
  242. ```
  243. One daemon, many sessions — and each session gets its **own tab state**. The server keys `activeTabIndex`, the ownership flag and a unique tab marker off the MCP session id, so session A physically cannot read or steer session B's tab.
  244. Two properties make this safe rather than merely tidy:
  245. - **Tab identity is a marker, not an index.** Each session stamps a unique id into the page it opens, so ownership survives navigation *and* survives the user reordering or closing other tabs. An index alone would silently drift onto the wrong tab.
  246. - **It fails closed.** If a session's marked tab can't be re-found, every tool refuses instead of falling back to whatever tab is in front — because that tab is usually yours:
  247. ```
  248. Tab tracking lost — refusing to fall back to "current tab of window"
  249. (would target the user's active tab). Call safari_new_tab to reopen.
  250. ```
  251. This also drops process count sharply: ~17 node processes for 17 concurrent sessions becomes 1.
  252. `SAFARI_PROFILE` stays optional — leave it unset and sessions bind to your ordinary Safari windows, cookies and logins intact. Details in [docs/http-transport-design.md](docs/http-transport-design.md).
  253. Prefer stdio (one process per agent) over a persistent daemon? That works too — isolation then comes from the process boundary itself. One caveat: if your client multiplexes agents through [mcporter](https://github.com/openclaw/mcporter), mcporter caches a single MCP client for all of them — whichever transport you pick — so the server never sees distinct sessions and per-session isolation can't engage. [mcporter-lanes](https://pi.dev/packages/mcporter-lanes) (a pi extension by [@maxim](https://github.com/maxim), born out of [#76](https://github.com/achiya-automation/safari-mcp/issues/76)) fixes this upstream: each agent session gets its own daemon dir — and therefore its own safari-mcp — with an idle timeout so processes don't pile up.
  254. ---
  255. ## Acting on a tab you already have open
  256. By default the server touches only tabs it opened itself. Point it at one of yours and it refuses:
  257. ```
  258. Tab safety: refusing "click" — current tab (https://mail.example.com/inbox) was not
  259. opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.
  260. ```
  261. That default exists because early versions did click into and close people's tabs. But "read the article I'm looking at" and "fill in the form on my screen" are real, and reopening the page loses the session state that made your tab worth using. Set `SAFARI_MCP_ALLOW_USER_TABS=1` and an **explicit** `safari_switch_tab` adopts the tab instead of refusing it; from then on the session works in it like one of its own, and says so:
  262. ```json
  263. { "tabIndex": 3, "safeUrl": "https://mail.example.com/inbox", "note": "(user tab, opted-in)" }
  264. ```
  265. What the flag deliberately does *not* do:
  266. - **It unlocks adoption, not the guards.** Only `safari_switch_tab` adopts, and only the tab you named. An ordinary click or navigate still never lands on whatever tab happens to be in front — the server acts on the tab you pointed it at, not the one you wandered to.
  267. - **`safari_close_tab` still refuses.** Closing is the one action whose cost you cannot undo, so an adopted tab is writable, never disposable. Close it yourself.
  268. - **Adoption is session-local.** Nothing is written to the shared ownership file, so it ends with the session rather than leaking to the next process on the machine.
  269. `safari_doctor` prints the flag's state, and every operation on an adopted tab logs `(user tab, opted-in)` — so "why did it touch my tab" has an answer instead of being a mystery. Default off; set it only for agents you want working inside your own browsing session. Designed in [#92](https://github.com/achiya-automation/safari-mcp/issues/92).
  270. ---
  271. ## Environment variables
  272. | Variable | Default | What it does |
  273. |----------|---------|--------------|
  274. | `SAFARI_MCP_HTTP` | off | Run one shared HTTP daemon instead of a process per client (see above). |
  275. | `SAFARI_MCP_HTTP_PORT` | `9225` | Port for that daemon. |
  276. | `SAFARI_PROFILE` | unset | Bind sessions to a named Safari profile. Unset = your ordinary windows. |
  277. | `SAFARI_MCP_ALLOW_USER_TABS` | off | Let `safari_switch_tab` adopt a tab **you** already had open, instead of refusing it (see below). |
  278. | `MCP_MAX_TABS` | `6` | Tabs one session may keep open. Opening one more closes that session's oldest tab, and `safari_new_tab` names it in `evictedTab` (its receipt). |
  279. | `SAFARI_MCP_RAISE_ON_NAVIGATE` | off | Let navigation bring Safari to the front, and stop the focus guard from putting your previous app back. |
  280. | `SAFARI_MCP_TOOLS` | all | `core` registers only the everyday tools (tabs, navigation, snapshot, reading, clicks, forms, evaluate, console, network, doctor), or give a comma list of tool names. For clients that load every tool definition up front. |
  281. | `SAFARI_MCP_SCREENSHOT_MAX_WIDTH` | unset | Downscale every `safari_screenshot` to this pixel width (Retina captures are 2× the viewport). Per-call `maxWidth` overrides it. |
  282. | `SAFARI_MCP_KEEPALIVE_TAB` | off | Keep one daemon-served page open in the profile window so Safari never parks the extension worker between commands. |
  283. | `SAFARI_MCP_OPEN_WINDOW_CMD` | unset | Command run with the profile name when the profile window is absent (e.g. after a reboot). Must open the window without focusing Safari. |
  284. `SAFARI_MCP_RAISE_ON_NAVIGATE=1` is for agents whose whole point is *showing* you a page — a voice assistant answering "open YouTube", a demo driver. Everything else should leave it off: by default Safari MCP works in the background and hands focus back to whatever app you were using, so an agent can drive a page while you keep typing somewhere else.
  285. ---
  286. ## Tools (98)
  287. <details>
  288. <summary><b>Click to expand the full tool list — organized by category</b></summary>
  289. ### Navigation (4)
  290. | Tool | Description |
  291. |------|-------------|
  292. | `safari_navigate` | Navigate to URL (auto HTTPS, wait for load) |
  293. | `safari_go_back` | Go back in history |
  294. | `safari_go_forward` | Go forward in history |
  295. | `safari_reload` | Reload page (optional hard reload) |
  296. ### Page Reading (3)
  297. | Tool | Description |
  298. |------|-------------|
  299. | `safari_read_page` | Get title, URL, and text content |
  300. | `safari_get_source` | Get full HTML source |
  301. | `safari_navigate_and_read` | Navigate + read in one call |
  302. ### Click & Interaction (6)
  303. | Tool | Description |
  304. |------|-------------|
  305. | `safari_click` | Click by CSS selector, visible text, or coordinates |
  306. | `safari_double_click` | Double-click (select word, etc.) |
  307. | `safari_right_click` | Right-click (context menu) |
  308. | `safari_hover` | Hover over element |
  309. | `safari_click_and_wait` | Click + wait for navigation |
  310. | `safari_click_and_read` | Click then return the updated page — saves a round-trip (React Router + full loads) |
  311. ### Form Input (11)
  312. | Tool | Description |
  313. |------|-------------|
  314. | `safari_fill` | Fill input (React/Vue/Angular compatible) |
  315. | `safari_clear_field` | Clear input field |
  316. | `safari_select_option` | Select dropdown option |
  317. | `safari_fill_form` | Batch fill multiple fields |
  318. | `safari_fill_and_submit` | Fill form + submit in one call |
  319. | `safari_type_text` | Type real keystrokes (JS-based, no System Events) |
  320. | `safari_press_key` | Press key with modifiers |
  321. | `safari_react_select_set` | Set a react-select v5 value via React fiber — bypasses the menu UI |
  322. | `safari_react_select_list_options` | List a react-select v5 dropdown's options without opening it |
  323. | `safari_replace_editor` | Replace all content in a code editor (Monaco, CodeMirror, Ace, ProseMirror) |
  324. | `safari_verify_state` | Verify an editor's framework-level state matches expected — catch stale DOM before Submit |
  325. ### Screenshots & PDF (3)
  326. | Tool | Description |
  327. |------|-------------|
  328. | `safari_screenshot` | Screenshot as PNG (viewport or full page) |
  329. | `safari_screenshot_element` | Screenshot a specific element |
  330. | `safari_save_pdf` | Export page as PDF |
  331. ### Scroll (3)
  332. | Tool | Description |
  333. |------|-------------|
  334. | `safari_scroll` | Scroll up/down by pixels |
  335. | `safari_scroll_to` | Scroll to exact position |
  336. | `safari_scroll_to_element` | Smooth scroll to element |
  337. ### Tab Management (5)
  338. | Tool | Description |
  339. |------|-------------|
  340. | `safari_list_tabs` | List all tabs (index, title, URL) |
  341. | `safari_new_tab` | Open new tab (background, no focus steal) |
  342. | `safari_close_tab` | Close tab |
  343. | `safari_switch_tab` | Switch to tab by index |
  344. | `safari_wait_for_new_tab` | Wait for a new tab (e.g. OAuth popup) and auto-switch to it |
  345. ### Wait (2)
  346. | Tool | Description |
  347. |------|-------------|
  348. | `safari_wait_for` | Wait for element, text, or URL change |
  349. | `safari_wait` | Wait for specified milliseconds |
  350. ### JavaScript (3)
  351. | Tool | Description |
  352. |------|-------------|
  353. | `safari_evaluate` | Execute arbitrary JavaScript, return result |
  354. | `safari_eval_file` | Execute JavaScript read from a file path (avoids huge inline scripts) |
  355. | `safari_list_frames` | List every document in the tab (main page + each iframe) with frameId, URL and text length — pass a frameId to `safari_evaluate`'s `frame` to run inside a cross-origin iframe |
  356. ### Element Inspection (4)
  357. | Tool | Description |
  358. |------|-------------|
  359. | `safari_get_element` | Element details (tag, rect, attrs, visibility) |
  360. | `safari_query_all` | Find all matching elements |
  361. | `safari_get_computed_style` | Computed CSS styles |
  362. | `safari_detect_forms` | Auto-detect all forms with field selectors |
  363. ### Accessibility (2)
  364. | Tool | Description |
  365. |------|-------------|
  366. | `safari_accessibility_snapshot` | Full a11y tree: roles, ARIA, focusable elements |
  367. | `safari_snapshot` | Accessibility tree with ref IDs for every interactive element — preferred way to see page state |
  368. ### Drag & Drop (1)
  369. | Tool | Description |
  370. |------|-------------|
  371. | `safari_drag` | Drag between elements or coordinates |
  372. ### File Operations (2)
  373. | Tool | Description |
  374. |------|-------------|
  375. | `safari_upload_file` | Upload file via JS DataTransfer (no file dialog!) |
  376. | `safari_paste_image` | Paste image into editor (no clipboard touch!) |
  377. ### Dialog & Window (2)
  378. | Tool | Description |
  379. |------|-------------|
  380. | `safari_handle_dialog` | Handle alert/confirm/prompt |
  381. | `safari_resize` | Resize browser window |
  382. ### Device Emulation (2)
  383. | Tool | Description |
  384. |------|-------------|
  385. | `safari_emulate` | Emulate device (iPhone, iPad, Pixel, Galaxy) |
  386. | `safari_reset_emulation` | Reset to desktop |
  387. ### Cookies & Storage (11)
  388. | Tool | Description |
  389. |------|-------------|
  390. | `safari_get_cookies` | Get all cookies |
  391. | `safari_set_cookie` | Set cookie with all options |
  392. | `safari_delete_cookies` | Delete one or all cookies |
  393. | `safari_local_storage` | Read localStorage |
  394. | `safari_set_local_storage` | Write localStorage |
  395. | `safari_delete_local_storage` | Delete/clear localStorage |
  396. | `safari_session_storage` | Read sessionStorage |
  397. | `safari_set_session_storage` | Write sessionStorage |
  398. | `safari_delete_session_storage` | Delete/clear sessionStorage |
  399. | `safari_export_storage` | Export all storage as JSON (backup/restore sessions) |
  400. | `safari_import_storage` | Import storage state from JSON |
  401. ### Clipboard (2)
  402. | Tool | Description |
  403. |------|-------------|
  404. | `safari_clipboard_read` | Read clipboard text |
  405. | `safari_clipboard_write` | Write text to clipboard |
  406. ### Network (6)
  407. | Tool | Description |
  408. |------|-------------|
  409. | `safari_network` | Quick network requests via Performance API |
  410. | `safari_start_network_capture` | Start detailed capture (fetch + XHR) |
  411. | `safari_network_details` | Get captured requests with headers/timing |
  412. | `safari_clear_network` | Clear captured requests |
  413. | `safari_mock_route` | Mock network responses (intercept fetch/XHR) |
  414. | `safari_clear_mocks` | Remove all network mocks |
  415. ### Console (4)
  416. | Tool | Description |
  417. |------|-------------|
  418. | `safari_start_console` | Start capturing console messages |
  419. | `safari_get_console` | Get all captured messages |
  420. | `safari_clear_console` | Clear captured messages |
  421. | `safari_console_filter` | Filter by level (log/warn/error) |
  422. ### Performance (2)
  423. | Tool | Description |
  424. |------|-------------|
  425. | `safari_performance_metrics` | Navigation timing, Web Vitals, memory |
  426. | `safari_throttle_network` | Simulate slow-3g/fast-3g/4g/offline |
  427. ### Data Extraction (4)
  428. | Tool | Description |
  429. |------|-------------|
  430. | `safari_extract_tables` | Tables as structured JSON |
  431. | `safari_extract_meta` | All meta: OG, Twitter, JSON-LD, canonical |
  432. | `safari_extract_images` | Images with dimensions and loading info |
  433. | `safari_extract_links` | Links with rel, external/nofollow detection |
  434. ### Advanced (7)
  435. | Tool | Description |
  436. |------|-------------|
  437. | `safari_override_geolocation` | Override browser geolocation |
  438. | `safari_list_indexed_dbs` | List IndexedDB databases |
  439. | `safari_get_indexed_db` | Read IndexedDB records |
  440. | `safari_css_coverage` | Find unused CSS rules |
  441. | `safari_analyze_page` | Full page analysis in one call |
  442. | `safari_doctor` | Diagnose the macOS permission + daemon chain (Apple Events, Accessibility, Screen Recording, codesign) with per-failure fixes |
  443. | `safari_reload_extension` | Hot-reload the Safari MCP Bridge extension without a manual toggle |
  444. ### Automation (1)
  445. | Tool | Description |
  446. |------|-------------|
  447. | `safari_run_script` | Run multiple actions in a single call (batch) |
  448. ### Native Input — CGEvent (4)
  449. | Tool | Description |
  450. |------|-------------|
  451. | `safari_native_click` | OS-level mouse click (CGEvent, `isTrusted: true`) — bypasses WAF/bot detection when `safari_click` is blocked (405/403) |
  452. | `safari_native_hover` | OS-level cursor hover — triggers real `:hover`/`mouseenter` for tooltips and obfuscated UIs |
  453. | `safari_native_type` | Insert text via the real paste pipeline — ProseMirror/Slate/Draft.js process it natively so Submit sends real data |
  454. | `safari_native_keyboard` | OS-level keypress + modifiers to Safari, no focus steal — reaches React trust-gated handlers (Discord/Slack send) |
  455. ### iOS & WebKit Validation (4)
  456. | Tool | Description |
  457. |------|-------------|
  458. | `safari_inspect_viewport` | Validate the `<meta name=viewport>` tag for iOS Safari (device-width, zoom/WCAG, viewport-fit) |
  459. | `safari_safe_area_insets` | Read live safe-area-inset values + viewport-fit / `env()` usage (notch / Dynamic Island) |
  460. | `safari_check_pwa` | Audit iOS "Add to Home Screen" / PWA readiness (apple-touch-icon, manifest, theme-color, splash) |
  461. | `safari_webkit_compat` | Check page CSS against this Safari via `CSS.supports()` — unsupported props, missing `-webkit-` prefixes, known quirks |
  462. </details>
  463. ---
  464. ## Security
  465. Safari MCP runs locally on your Mac with minimal attack surface:
  466. | Aspect | Detail |
  467. |--------|--------|
  468. | Network | **No remote connections** — all communication is local (stdio + localhost) |
  469. | Permissions | macOS system permissions required (Screen Recording for screenshots) |
  470. | Data | No telemetry, no analytics, no data sent anywhere |
  471. | Extension | Communicates only with the local profile bridges (`localhost:9224/9228/9232/9236`), validated by Safari |
  472. | Pairing | The bridge token never leaves your Mac and is not in the app. `npx safari-mcp pair` prints a one-time 8-character code (10 minutes, 5 tries); the bridge hands its token only to an extension origin that presents it |
  473. | Code | Fully open source (MIT) — audit every line |
  474. ---
  475. ## Safari MCP vs Alternatives
  476. | Feature | Safari MCP | Chrome DevTools MCP | Playwright MCP |
  477. |---------|:----------:|:-------------------:|:--------------:|
  478. | CPU/Heat | 🟢 Minimal | 🔴 High | 🟡 Medium |
  479. | Your logins | ✅ Yes | ✅ Yes | ❌ No |
  480. | macOS native | ✅ WebKit | ❌ Chromium | ❌ Chromium/WebKit |
  481. | Browser dependencies | None | Chrome + debug port | Playwright runtime |
  482. | Tools | 98 | ~30 | ~25 |
  483. | File upload | JS (no dialog) | CDP | Playwright API |
  484. | Image paste | JS (no clipboard) | CDP | Playwright API |
  485. | Focus steal | ❌ Background | ❌ Background | ❌ Headless |
  486. | Network mocking | ✅ | ❌ | ✅ |
  487. | Lighthouse | ❌ | ✅ | ❌ |
  488. | Performance trace | ❌ | ✅ | ❌ |
  489. > **Tip:** Use Safari MCP for daily browsing tasks (95% of work) and Chrome DevTools MCP only for Lighthouse/Performance audits.
  490. ### vs Apple's Official Safari MCP (safaridriver)
  491. In July 2026 Apple shipped an **official** Safari MCP server built on `safaridriver` — first in Safari Technology Preview 247, and in stable Safari since 27.0. That's great validation for the category — and it's built for a different job. Apple's server drives an **isolated WebDriver automation session** for debugging; safari-mcp drives the **real Safari you're already logged into**.
  492. On macOS 27.0 with Safari 27.0, `safaridriver --help` lists `--mcp` and its `tools/list` answers with 17 entries (verified 2026-09-15); Safari 26.5.2 had no `--mcp` (verified 2026-07-23). Check your own machine with `safaridriver --help | grep mcp`.
  493. > **Running both?** Apple's setup guide registers its server under the name `safari-mcp` (`claude mcp add safari-mcp -- /usr/bin/safaridriver --mcp`) — the same name as this package. Give one of them a different name, e.g. `claude mcp add safari-webdriver -- /usr/bin/safaridriver --mcp`, so your client doesn't overwrite one with the other or leave you guessing which server answered.
  494. | | 🦁 safari-mcp *(this repo)* | Apple `safaridriver --mcp` |
  495. |---|:---:|:---:|
  496. | **Your real logins / cookies** | ✅ Your actual Safari | ⚠️ Isolated automation session — no access to AutoFill or browsing activity |
  497. | **Runs on** | ✅ Stable Safari, every Mac | ⚠️ Safari 27 or later, or Safari Technology Preview 247+ |
  498. | **Background (no focus steal)** | ✅ Yes | ❌ Dedicated window with a "controlled by automation" banner |
  499. | **Page sees `navigator.webdriver`** | ✅ `false` — an ordinary tab | ⚠️ `true` — required of every WebDriver session |
  500. | **Tools** | **98** | 17 |
  501. | **Storage** (cookies, localStorage, IndexedDB) | ✅ 10 tools | ❌ |
  502. | **Network mocking + throttling** | ✅ Yes | ❌ Read-only network inspection |
  503. | **Device emulation** (iPhone, iPad) | ✅ Yes | ⚠️ Viewport + media type only |
  504. | **Setup** | `npx safari-mcp` | Enable "Allow remote automation and external agents" in Safari's Developer settings, then point your client at `safaridriver --mcp` |
  505. | **Official Apple support** | ❌ Community (MIT) | ✅ Apple, WebDriver-standard |
  506. > **About that `navigator.webdriver` row:** the WebDriver standard requires every remote-controlled session to report `true`, so Apple's server does. safari-mcp evaluates JavaScript in an ordinary tab, so it reads `false` (checked on Safari 27.0, 2026-09-17). That is the difference if a site refuses WebDriver traffic. It is not an anti-detection feature — nothing else about the browser is disguised, and your real logins are in use, so treat every page as if it knows exactly who you are.
  507. > **When Apple's server is the right pick:** you specifically want a clean-room, WebDriver-standard session for compatibility debugging on Safari 27 or later. **For everything else — daily automation on the browser you're already signed into, in the background — safari-mcp is built for exactly that.**
  508. ### Why Safari MCP and Not the Other Safari MCP Projects?
  509. There are several "safari-mcp" projects floating around. Here's how they compare:
  510. | Feature | **🦁 safari-mcp** *(this repo)* | [lxman/safari-mcp-server](https://github.com/lxman/safari-mcp-server) | [Epistates/MCPSafari](https://github.com/Epistates/MCPSafari) | [HayoDev/safari-devtools-mcp](https://github.com/HayoDev/safari-devtools-mcp) |
  511. |---------|:------------------------------:|:----------------------:|:------------:|:----------------------:|
  512. | **Tools** | **98** | ~10 | 23 | ~15 |
  513. | **Install** | `npx safari-mcp` | Manual | Binary | `npx` |
  514. | **Engine** | **Dual** (Extension + AppleScript) | WebDriver | Extension only | DevTools Protocol |
  515. | **Keeps your real Safari logins** | ✅ Yes | ⚠️ Limited | ✅ Yes | ❌ Debug session |
  516. | **Background (no focus steal)** | ✅ Yes | ❌ No | ⚠️ Sometimes | ✅ Yes |
  517. | **Storage tools** (cookies, localStorage, IndexedDB) | **10** | 0 | 0 | 2 |
  518. | **Data extraction** (tables, meta, images, links) | **4** | 0 | 0 | 0 |
  519. | **Network mocking** | ✅ Yes | ❌ No | ❌ No | ❌ No |
  520. | **Device emulation** (iPhone, iPad, Pixel) | ✅ Yes | ❌ No | ❌ No | ❌ No |
  521. | **File upload** (no dialog) | ✅ JS DataTransfer | ❌ No | ❌ No | ❌ No |
  522. | **Image paste** (no clipboard touch) | ✅ Yes | ❌ No | ❌ No | ❌ No |
  523. | **PDF export** | ✅ Yes | ❌ No | ❌ No | ❌ No |
  524. | **Console capture** | **4 tools** | 0 | 1 | 1 |
  525. | **Performance metrics + Web Vitals** | ✅ Yes | ❌ No | ❌ No | ⚠️ Partial |
  526. | **Active maintenance** | ✅ Multiple releases/week | 🟡 Sporadic | 🟡 Slow | 🟡 Slow |
  527. | **License** | **MIT** | MIT | None specified | MIT |
  528. | **In MCP Registry** | ✅ | ❌ | ❌ | ✅ |
  529. | **In Awesome MCP** | ✅ | ❌ | ❌ | ❌ |
  530. > **TL;DR** — if you want the most complete Safari MCP with the smoothest install, the most tools, and active maintenance, **this is the one**.
  531. ---
  532. ## Architecture
  533. Safari MCP uses a **dual-engine** architecture — the Extension is preferred for speed and advanced capabilities, with AppleScript as an always-available fallback:
  534. ```
  535. Claude/Cursor/AI Agent
  536. ↓ MCP Protocol (stdio)
  537. Safari MCP Server (Node.js)
  538. ↓ ↓
  539. Extension (HTTP) AppleScript + Swift daemon
  540. (~5-20ms/cmd) (~5ms/cmd, always available)
  541. ↓ ↓
  542. Content Script do JavaScript in tab N
  543. ↓ ↓
  544. Page DOM ←←←←←←←←←← Page DOM
  545. ```
  546. **Key design decisions:**
  547. - **Dual engine with automatic fallback** — Extension is preferred; if not connected, AppleScript handles everything seamlessly
  548. - **Persistent Swift helper** — one long-running process instead of spawning per command (16x faster)
  549. - **Tab-indexed operations** — all JS runs on a specific tab by index, never steals visual focus
  550. - **JS-first approach** — typing, clicking, file upload all use JavaScript events (no System Events keyboard conflicts)
  551. - **No `activate`** — Safari is never brought to foreground
  552. ---
  553. ## Safari Extension (Optional)
  554. The Safari MCP Extension is **optional but recommended**. Without it, ~80% of functionality works via AppleScript alone. The extension adds capabilities that AppleScript cannot provide:
  555. ### What the Extension Adds
  556. | Capability | With Extension | AppleScript Only |
  557. |-----------|:--------------:|:----------------:|
  558. | Closed Shadow DOM (Reddit, Web Components) | ✅ Full access | ❌ Invisible |
  559. | Strict CSP sites | ✅ Bypasses via MAIN world | ❌ Often blocked |
  560. | React/Vue/Angular state manipulation | ✅ Deep (Fiber, ProseMirror) | ⚠️ Basic |
  561. | Loading state detection (spinners, skeletons) | ✅ Smart detection | ❌ No |
  562. | Dialog handling (alert/confirm) | ❌ | ✅ Only AppleScript |
  563. | Native OS-level click (CGEvent) | ❌ | ✅ Only AppleScript |
  564. | PDF export | ❌ | ✅ Only AppleScript |
  565. > **When do you need the extension?** If you're automating modern SPAs with closed shadow DOM (e.g., Reddit), sites with strict Content Security Policy, or framework-heavy editors (Draft.js, ProseMirror, Slate).
  566. ### Installing the Extension
  567. No Xcode needed. The app is signed with a Developer ID and notarized by Apple.
  568. 1. **Download** [`Safari-MCP.app.zip`](https://github.com/achiya-automation/safari-mcp/releases/latest/download/Safari-MCP.app.zip) from the latest release, unzip it, and move **Safari MCP.app** to `/Applications`.
  569. 2. **Open the app once.** That registers the extension with Safari. Click **Quit and Open Safari Settings…**.
  570. 3. **Turn it on** in Safari → Settings → Extensions → **Safari MCP Bridge**. When Safari asks, allow it on every website: it needs page access to run commands, and it talks only to the local bridge. If you use Safari profiles, turn it on in each profile you automate (Settings → Profiles → *profile* → Extensions).
  571. 4. **Pair it.** With your MCP client running (it starts safari-mcp), run:
  572. ```bash
  573. npx safari-mcp pair
  574. ```
  575. Click the Safari MCP button in Safari's toolbar, enter the code, and click **Pair**. The badge changes from **PAIR** to **ON**. A code works once and expires after 10 minutes. Each Safari profile pairs once, so run the command again for the next profile.
  576. To update, download the new zip when a release says the extension changed and replace the app. The pairing stays.
  577. The extension connects to the first local bridge whose declared Safari profile matches its own. The default bridge ports are `9224`, `9228`, `9232`, and `9236`; a single-profile setup normally uses `9224`.
  578. <details>
  579. <summary><b>Building the extension from source (contributors)</b></summary>
  580. A build from source needs Xcode (free in the App Store). The npm package does not include the `xcode/` directory, so clone the repository:
  581. ```bash
  582. # 1. Clone the repo
  583. git clone https://github.com/achiya-automation/safari-mcp.git
  584. cd safari-mcp
  585. # 2. Build a clean, Apple Development-signed app
  586. # If needed, first choose your Team in Xcode → Signing & Capabilities.
  587. xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
  588. -scheme "Safari MCP (macOS)" -configuration Release \
  589. -allowProvisioningUpdates clean build
  590. # 3. Locate the signed app
  591. APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release -name "Safari MCP.app" -maxdepth 2 | head -1)
  592. # 4. Re-sign safari-helper with the Apple Events entitlement
  593. # (helps macOS surface the TCC Automation prompt reliably).
  594. # Keep the stable identifier: macOS keys the Accessibility grant to it.
  595. codesign --sign - --force --identifier com.achiya-automation.safari-mcp \
  596. --entitlements safari-helper.entitlements safari-helper
  597. # 5. Open the app (needed once so Safari registers the extension)
  598. open "$APP_PATH"
  599. ```
  600. A local build embeds this Mac's bridge token (`~/.safari-mcp-bridge-token`) as a private resource, so it connects without pairing. Pairing still works on a local build and takes precedence over the built-in token.
  601. > **Do not ad-hoc re-sign `Safari MCP.app` with `codesign --deep --sign -`.** That replaces the Apple Development identity on the wrapper and embedded extension; current Safari can then silently disable or mark the extension as removed. If a previous build was ad-hoc signed, run the `clean build` command above again.
  602. Alternatively, open `xcode/Safari MCP/Safari MCP.xcodeproj` directly in Xcode, select your Apple ID under Signing & Capabilities, and click Run. A free personal Apple Developer account is sufficient for local use.
  603. Then in Safari:
  604. 1. Safari → Settings → Advanced → enable **Show features for web developers**
  605. 2. Safari → Settings → Developer → **Allow unsigned extensions** (required each Safari restart)
  606. 3. Safari → Settings → Extensions → enable **Safari MCP Bridge**
  607. > **Note:** "Allow unsigned extensions" resets every time Safari restarts. You'll need to re-enable it in Safari → Settings → Developer after each restart. The extension itself stays installed. The downloaded, notarized app does not need this setting.
  608. Maintainers publish the downloadable app with `scripts/release-app.sh`, which archives without a bridge token, exports with a Developer ID, notarizes, staples, and attaches `Safari-MCP.app.zip` to the GitHub release.
  609. </details>
  610. **Toolbar icon status:**
  611. - **ON** — connected to MCP server
  612. - **PAIR** — not paired yet, or the bridge no longer accepts its pairing: run `npx safari-mcp pair` and enter the code in the popup
  613. - **OFF** — manually disabled via popup
  614. - *(no badge)* — server not running, will auto-reconnect
  615. ---
  616. ## macOS Permissions
  617. Safari MCP needs these one-time permissions:
  618. | Permission | Where | Why |
  619. |-----------|-------|-----|
  620. | JavaScript from Apple Events | Safari → Settings → Developer | Required for `do JavaScript` |
  621. | Automation → Safari | System Settings → Privacy & Security → Automation | Required for all AppleScript-backed tools |
  622. | Screen Recording | System Settings → Privacy & Security → Screen & System Audio Recording | Required for `safari_screenshot` without the extension, and for `safari_save_pdf` |
  623. | Accessibility (safari-helper) | System Settings → Privacy & Security → Accessibility (named **Device Control and Data Access** on macOS 27) | Required for `safari_native_click`, `safari_native_keyboard`, `safari_native_hover` and `safari_save_pdf` |
  624. ### Granting Accessibility to safari-helper (required for `safari_native_*`)
  625. The `safari_native_click`, `safari_native_keyboard` and `safari_native_hover` tools inject OS-level `CGEvent` events into Safari without stealing focus. macOS requires the underlying helper binary to be approved in **Accessibility** before those events can reach a non-frontmost window.
  626. 1. Open **System Settings → Privacy & Security → Accessibility** (on macOS 27 the pane is named **Device Control and Data Access**).
  627. 2. Click `+` (unlock with your password if needed).
  628. 3. Navigate to the helper binary and add it:
  629. - npm global install: `$(npm root -g)/safari-mcp/safari-helper`
  630. - npx / project install: `./node_modules/safari-mcp/safari-helper`
  631. - From source clone: `/path/to/safari-mcp/safari-helper`
  632. 4. Make sure the toggle next to it is **ON**.
  633. The postinstall script re-signs the helper with a stable identifier (`com.achiya-automation.safari-mcp`) so this permission survives future upgrades — without that step, every `npm update` would silently revoke approval because the binary's adhoc-signed identifier changes per build.
  634. If `safari_native_click` reports success but the page doesn't react (no `isTrusted: true` click events fire), the helper is most likely missing this approval. The `safari_*` (non-`native_`) tools don't need it.
  635. ### Granting Automation → Safari (important for IDE users)
  636. macOS TCC grants Automation permission to the **parent process** that spawns the MCP server, not to `safari-mcp` itself. So you need to grant **Automation → Safari** to the app that runs Claude Code / Cursor / Windsurf — typically **Visual Studio Code** or **Terminal**.
  637. If the permission dialog never appears automatically, run this command once from a Terminal that already has Automation permission:
  638. ```bash
  639. osascript -e 'tell application "Safari" to get URL of current tab of window 1'
  640. ```
  641. That call registers the Terminal app in the Automation database and then triggers the prompt for Safari. After you approve it, subsequent MCP calls from any child process chain will work.
  642. ---
  643. ## Troubleshooting
  644. | Issue | Fix |
  645. |-------|-----|
  646. | "AppleScript error" | Enable "Allow JavaScript from Apple Events" in Safari → Settings → Developer |
  647. | "Not authorized to send Apple events to Safari" | Grant Automation → Safari to your IDE (see above) |
  648. | "Not authorized" after `npm update` | Updating changes the binary's cdhash — macOS silently revokes Automation permission. Re-run the `osascript` one-liner above to re-grant it |
  649. | `safari_native_click` reports success but page doesn't react | Add `safari-helper` to **System Settings → Privacy & Security → Accessibility** (see [Granting Accessibility](#granting-accessibility-to-safari-helper-required-for-safari_native_) above). Confirm by attaching a `click` listener with `{capture:true}` in the page console — without the grant, no `isTrusted: true` event fires |
  650. | Screenshots empty | Grant Screen & System Audio Recording to Terminal/VS Code — or, when safari-mcp runs as a LaunchAgent, to the `node` binary itself (a Homebrew node upgrade changes its path, so re-grant after upgrading). `safari_doctor` names the exact binary |
  651. | Extension missing after enabling "Allow unsigned extensions" (macOS 27) | Known macOS 27.0 issue (183044008): with the setting on, rebuild the extension app (see [Installing the Extension](#installing-the-extension)) and it appears |
  652. | Popup says **Not paired** or **Pairing needed** | Run `npx safari-mcp pair` while your MCP client is running and enter the code in the popup. "Pairing needed" means the bridge's token changed since the last pairing (for example, `~/.safari-mcp-bridge-token` was deleted) |
  653. | Popup says the server is **too old to pair** | Your MCP client runs a safari-mcp from before pairing existed. Update it (`npx safari-mcp@latest`) and restart the client |
  654. | Tab not found | Call `safari_list_tabs` to refresh tab indices |
  655. | Hebrew keyboard issues | All typing uses JS events — immune to keyboard layout |
  656. | HTTPS blocked | `safari_navigate` auto-tries HTTPS first, falls back to HTTP |
  657. | Safari steals focus | Ensure you're on latest version — `newTab` restores your active tab |
  658. ---
  659. ## FAQ
  660. <details>
  661. <summary><b>Does it work with Safari Technology Preview?</b></summary>
  662. No. Every AppleScript path targets `application "Safari"` and the native helper looks for the bundle id `com.apple.Safari`, so STP (`com.apple.SafariTechnologyPreview`) is a different application that safari-mcp never addresses. Run it against stable Safari.
  663. Note that Apple's *own* `safaridriver --mcp` server is the one that needs STP 247+ (or Safari 27+) — see [Safari MCP vs Alternatives](#safari-mcp-vs-alternatives). The two are unrelated.
  664. </details>
  665. <details>
  666. <summary><b>Can it handle private/incognito tabs?</b></summary>
  667. Not as a supported mode, and it is untested. No tool opens a private window, and Safari disables extensions in Private Browsing unless you turn each one on explicitly, so the extension bridge — and everything in the "With Extension" column of [Safari Extension (Optional)](#safari-extension-optional) — is off there by default.
  668. If you want an isolated identity, use a separate Safari **profile** instead: profile windows are a first-class concept here (see [Running several agents at once](#running-several-agents-at-once)).
  669. </details>
  670. <details>
  671. <summary><b>Does it work with multiple Safari windows?</b></summary>
  672. Yes. Tab lookups walk `every window` rather than assuming window 1, and a tab is pinned by its window's `(index, tabCount)` pair, because an index on its own is ambiguous once two windows are open. Profile windows are recognised by Safari's `ProfileName — Tab Title` window naming.
  673. The reliable handle is still the **receipt** that `safari_new_tab` returns: pass it to every later call and the tab is addressed directly, no matter how many windows move around it.
  674. </details>
  675. <details>
  676. <summary><b>What macOS versions are supported?</b></summary>
  677. Any macOS with Safari — the package declares `"os": ["darwin"]` and no minimum OS, and there is no version gate in the code. Node.js 20+ is the hard requirement (`"engines": { "node": ">=20" }`).
  678. Two places where the OS does matter in practice:
  679. - On **macOS 27** the Accessibility pane is renamed **Device Control and Data Access** — same grant, new name (see [macOS Permissions](#macos-permissions)).
  680. - Safari 26 and 27 changed several web-platform behaviours that specific tools account for; those are handled, not blocked.
  681. </details>
  682. <details>
  683. <summary><b>Can I run multiple instances simultaneously?</b></summary>
  684. Yes — that is what [Running several agents at once](#running-several-agents-at-once) covers. Each session owns its own tabs, and ownership is tracked per session rather than by tab index, so one agent cannot act on (or close) a tab another agent owns.
  685. One process binds the extension bridge port; the others proxy through it and take the port over if that process exits.
  686. </details>
  687. <details>
  688. <summary><b>Do I need to keep Safari in the foreground?</b></summary>
  689. No. `safari_new_tab` opens a **background** tab and never steals focus, and the few commands macOS forces an implicit activate on restore your previous frontmost app afterwards — with a guard that leaves focus alone if you were typing in Safari yourself a moment earlier.
  690. The two exceptions are the deliberately native tools — `safari_native_click`, `safari_native_keyboard`, `safari_native_hover` — which post real OS events and therefore land wherever the frontmost window is. Do not use those while you are working in another Safari tab.
  691. </details>
  692. <details>
  693. <summary><b>How does it interact with Safari extensions?</b></summary>
  694. Your existing extensions keep running normally; safari-mcp drives the same Safari you use, so content blockers and password managers behave exactly as they do for you.
  695. safari-mcp also ships **its own optional extension**. Without it roughly 80% of the tools still work over AppleScript alone; with it you additionally get closed shadow DOM, strict-CSP sites, deep framework state and loading-state detection. Dialog handling, native clicks and PDF export go the other way — those are AppleScript-only. The full split is in [Safari Extension (Optional)](#safari-extension-optional).
  696. </details>
  697. <details>
  698. <summary><b>What happens if "Allow JavaScript from Apple Events" is not enabled?</b></summary>
  699. Anything that evaluates JavaScript fails — `safari_evaluate`, `safari_read_page`, form filling, extraction — while pure AppleScript actions such as opening or switching tabs still work. That is the usual cause of "it opens the tab but reads nothing".
  700. Turn it on in **Safari → Settings → Advanced → Show features for web developers**, then **Safari → Settings → Developer → Allow JavaScript from Apple Events**. Both are listed under [Prerequisites](#prerequisites). `safari_doctor` walks the rest of the chain (Automation, native helper, Accessibility, Screen Recording) and names this setting in its fix hint — but its Apple Events check only counts windows, which Automation permission alone satisfies, so it will not fail on this one for you.
  701. </details>
  702. ## Works With
  703. Safari MCP works with any MCP-compatible client:
  704. | Client | Status |
  705. |--------|--------|
  706. | [Claude Code](https://claude.ai/claude-code) | ✅ Tested daily |
  707. | [Claude Desktop](https://claude.ai/download) | ✅ Tested |
  708. | [Cursor](https://cursor.sh) | ✅ Tested |
  709. | [Windsurf](https://codeium.com/windsurf) | ✅ Compatible |
  710. | [VS Code + Continue](https://continue.dev) | ✅ Compatible |
  711. ---
  712. ## Contributing
  713. PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.
  714. The codebase is two files:
  715. - `safari.js` — Safari automation layer (AppleScript + JavaScript)
  716. - `index.js` — MCP server with tool definitions
  717. ---
  718. ## Sponsors
  719. Safari MCP is free and open source. If it saves you time or CPU cycles, consider supporting its development:
  720. <a href="https://paypal.me/achiyaC123"><img src="https://img.shields.io/badge/Sponsor-PayPal-blue?logo=paypal" alt="Sponsor via PayPal"></a>
  721. Your support funds:
  722. - 🧪 Testing across macOS versions and Safari releases
  723. - 🛠️ New tools and features
  724. - 📖 Documentation and examples
  725. [Become the first sponsor!](https://paypal.me/achiyaC123)
  726. ---
  727. ## Commercial Support
  728. **Need Safari MCP integrated into your product or agent stack?** [Achiya Automation](https://achiya-automation.com/en/blog/safari-mcp-browser-automation/) offers:
  729. - **Priority bug fixes** and custom tool development for your use case
  730. - **Integration consulting** — wiring Safari MCP into production agent systems (Claude, Cursor, n8n, custom)
  731. - **Private deployment support** — multi-user Safari MCP, non-standard macOS environments, CI/CD
  732. - **Training workshops** for engineering teams adopting MCP-based automation
  733. Built by the author of Safari MCP. [Start a conversation →](https://achiya-automation.com/en/contact/)
  734. ---
  735. ## What agents unlock with Safari MCP
  736. When an AI agent drives Safari MCP, it gets things a headless browser can't:
  737. - **Real authenticated sessions** — Gmail, GitHub, Ahrefs, Slack, banking dashboards are all already logged in
  738. - **Framework-aware form filling** — `safari_fill_and_submit` calls React/Vue/Angular setters natively, no guessing whether `input` events fired
  739. - **Background operation** — the agent works in parallel while you keep using your Mac
  740. - **One MCP call per workflow** — `safari_run_script` batches navigation + clicks + extraction into a single roundtrip
  741. The pattern holds across models: **drive the browser the human already trusts** — you inherit logins, cookies, extensions, and the user's exact environment in one step.
  742. ---
  743. ## Community
  744. **6,000+ monthly npm downloads** — developers are building AI agents on macOS with Safari MCP.
  745. - [GitHub Discussions](https://github.com/achiya-automation/safari-mcp/discussions) — ask questions, share use cases
  746. - [Issues](https://github.com/achiya-automation/safari-mcp/issues) — bug reports and feature requests
  747. - [![Good First Issues](https://img.shields.io/github/issues/achiya-automation/safari-mcp/good%20first%20issue?color=7057ff&label=good%20first%20issues)](https://github.com/achiya-automation/safari-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — start contributing
  748. ---
  749. ## Ecosystem
  750. Other macOS MCP servers that complement Safari MCP:
  751. | Project | What it does | When to use |
  752. |---------|-------------|-------------|
  753. | [mcp-server-macos-use](https://github.com/mediar-ai/mcp-server-macos-use) | OS-level macOS automation (accessibility, screen control) | System-wide interactions beyond Safari |
  754. | [chrome-devtools-mcp](https://github.com/anthropics/chrome-devtools-mcp) | Chrome DevTools Protocol | Lighthouse audits, Chrome-specific performance traces |
  755. > Using Safari MCP alongside Chrome DevTools MCP? Safari handles 95% of daily browsing (zero overhead), Chrome handles the 5% that needs Lighthouse or Chrome-specific traces.
  756. ---
  757. ## Listed On
  758. [![Glama](https://glama.ai/mcp/servers/achiya-automation/safari-mcp/badges/score.svg)](https://glama.ai/mcp/servers/achiya-automation/safari-mcp) [![MCP Registry](https://img.shields.io/badge/MCP-Registry-purple)](https://registry.modelcontextprotocol.io/) [![MCP Scoreboard](https://mcpscoreboard.com/badge/05977769-8762-4e89-aff3-a0c5776843bb.svg)](https://mcpscoreboard.com/server/05977769-8762-4e89-aff3-a0c5776843bb/) [![CI](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml)
  759. ---
  760. ## License
  761. MIT — use it however you want.
  762. ---
  763. Built by **[Achiya Automation](https://achiya-automation.com)** — automation & AI agents for business.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.