safari-mcp
by trmquang93
README.md
# safari-mcp
MCP server (stdio) that drives your real, logged-in Safari through `osascript`. No extension, no WebDriver.
**When to use it.** Prefer it for any real-world website or service (GitHub, dashboards, admin consoles, web apps you are signed in to): it is your real Safari, so logins and cookies already work. An agent app's built-in preview browser is isolated from those logins; keep it for localhost and dev servers only, even when the host app calls that browser its default. The server says this in its MCP `instructions` and in the `safari_open` and `safari_tabs` descriptions.
**Background by default.** It works in its own Safari window (the "agent window", created on first use and sent behind your windows; id kept in `~/.local/share/safari-mcp/agent-window`). `safari_open`, `safari_screenshot`, `safari_select_tab` and every default tab (`front`) act only inside that window, so your windows and current tabs are never switched. Same Safari profile, so your logins apply. The only tool that can take the foreground is `safari_native_key`, now a last resort (see *Editing without the keyboard* below).
Tools: `safari_tabs`, `safari_open`, `safari_select_tab`, `safari_close_tab`, `safari_js`, `safari_read`,
`safari_elements`, `safari_click`, `safari_set_caret`, `safari_select_text`, `safari_edit_text`, `safari_type`, `safari_upload`, `safari_press`, `safari_native_key`, `safari_dialog`, `safari_wait`, `safari_extract_to_file`, `safari_screenshot`, `safari_batch`.
## Editing without the keyboard (what changed)
Real keystrokes (`safari_native_key`) raise Safari and use the user's keyboard, and on Google Docs they landed on the wrong line (the caret a synthetic click saw was not the real caret; Cmd+Home even reached Safari's own shortcuts). Everything now has a background route that runs inside the page:
- `safari_click` sends events with the element's real coordinates and puts the **real caret/selection** where the click landed in contenteditable, input and textarea (`caret: start|end|none` to override; `x`/`y` for a point). On Google Docs `line: n` clicks the nth visible text line and **verifies Docs' own caret** landed on that line (it refuses otherwise).
- New `safari_set_caret`, `safari_select_text`, `safari_edit_text`: place the caret / select (`find` substring, or the whole element) / replace or insert text through the editing pipeline (`execCommand`, or Docs' hidden input iframe). No focus change, no System Events. `useSelection: true` replaces what a previous click/select left. On Docs the target is `line: n` or the text of a heading (found through the document outline); text is canvas, so lines are located from pixels and the result reports the line the caret ended on and the outline.
- `safari_press` is page-scoped (accepts `modifiers`): it can never reach Safari's chrome. In plain DOM editors it performs the key's default action (arrows, Home/End, Cmd+Up/Down, Shift-extend, Backspace, Enter, typing); on Docs it goes to Docs' input target (Cmd+Home/End are mapped to Docs' Cmd+Up/Down).
- `safari_native_key` keeps its schema but is guarded: needs `allowForeground: true` every call; refused within 3 s of the user's last keyboard/mouse activity; refused on Google Docs/Sheets/Slides; command/control combos need `allowShortcut: true` and Safari browser shortcuts (Cmd+Home/Up/Left/L/T/W...) are always refused; it checks Safari is frontmost and the page has focus before typing, and restores the previous app, the user's window/tab and the agent window's position afterwards.
- `safari_click` default coordinates changed from 0,0 to the element centre; `safari_type` on a contenteditable now replaces only that element's content (it used to select the whole editor). `safari_batch` accepts `set_caret`, `select_text` and `edit_text` steps.
- Docs limits: one visual line per `line`; `find` is unavailable (page text is not readable); clicking an outline heading adds `#heading=…` to the URL (same document).
## One-time Safari setup
Safari > Settings > Advanced > "Show features for web developers", then Develop > Developer Settings >
**Allow JavaScript from Apple Events**. First use also asks macOS Automation permission for the calling app.
Screenshots need Screen Recording permission for the calling app.
## Install
```
git clone git@github.com:trmquang93/safari-mcp.git ~/Projects/safari-mcp
cd ~/Projects/safari-mcp && npm install
claude mcp add --scope user safari -- node ~/Projects/safari-mcp/server.mjs
```
macOS only (uses `osascript`). Node 18+.
## Test
`npm test` (pure helpers), `npm run smoke:editor` (local contenteditable page: click a heading, replace it, Cmd+Home stays in the page, real keys refused, frontmost app unchanged) and `npm run smoke` (spawns the server, drives a real Safari tab on `test/page.html` in the agent window, closes it, and checks that your own windows and tabs are unchanged and Safari never became the frontmost app).
## Limits
- Main frame only: no iframes, no shadow DOM. Synthetic events only (`isTrusted=false`); a few sites ignore them.
- No real mouse. Real keystrokes only through `safari_native_key` (needs Accessibility permission for the app that runs the server; everything else works without it).
- Screenshot shows the window's *current* tab, so it switches to the requested tab first (harmless in the agent window; on one of your own tabs it changes what you see).
- Your own tabs are reachable only by an explicit spec (`url:`, `title:`, `1:3`); `url:`/`title:` search the agent window first. JS, click and type on your tab do not change focus.
- It acts as you in every site you are logged in to. Use `url:` / `title:` tab specs; `safari_close_tab` requires an explicit tab.
- Secrets: use `safari_extract_to_file` so values go page -> file (mode 600) and never into the conversation.
## Tips
**Tabs**
- Agent-window tabs have refs `agent:<n>` (returned by `safari_open`, listed by `safari_tabs`). New tabs append at the end, so a ref stays valid until a tab before it is closed. Your own windows are listed as `window:tab`, which shift whenever you reorder windows; prefer `url:` / `title:` for them.
- `safari_open mode=same_tab` navigates the agent window's current tab unless you pass `tab:`. `safari_screenshot` and `safari_select_tab` make a tab current, so pass `tab:` to avoid overwriting an unrelated tab.
- `safari_open` default (`new_tab`) does not change what screenshots show; use `foreground: true` to look at it.
**Clicks and typing**
- A click can "succeed" and still do nothing: some SPA controls (custom selects, menus, expansion panels) ignore events with `isTrusted=false`. Confirm with `safari_read` / `safari_screenshot` / `safari_elements`. If a dropdown does not open, focus it and try `safari_press` (`Down`, `Enter`); `safari_native_key` is the last resort.
- `safari_native_key` (needs `allowForeground: true`) raises Safari and uses the real keyboard for a moment, then restores the previous app and Safari window; it refuses while you are typing. Error `(1002) not allowed to send keystrokes` means Accessibility is not granted to the calling app.
- `safari_type` with `text:` resolves a label or wrapper to its input. If that fails, pass `selector:` (list inputs with `safari_elements selector:"input"`). Generated ids are only stable within one page view, so look them up each time.
- `safari_click text:"Save" exact:true`: without `exact`, "Save" also matches "Save as draft" and similar. Several dialogs can stack, so list candidates with `safari_elements` first.
- Overlays (select options, dialogs) render in separate containers: query them after opening, e.g. `safari_elements selector:"[role=option]"`.
**Native dialogs (alert / confirm / prompt / "discard unsaved changes")**
- Safari draws these itself and the page is blocked while one is open, so `safari_click` / `safari_js` time out (the error says so). Use `safari_dialog`: `action: read` shows the message and buttons (`No dialog is open` otherwise), `accept` presses OK/Leave (`text:` fills a `prompt()` first), `dismiss` presses Cancel/Stay.
- It reads Safari's accessibility tree and presses the button (AXPress): no focus change, no keystrokes, works in the background window. Needs Accessibility permission for the app that runs the server. The window is matched by title and the call refuses when two windows with that title both show a dialog.
**Batch and goal (`safari_batch`)**
- One call runs up to 30 steps in order (`open`, `click`, `type`, `press`, `wait`, `js`, `read`, `elements`, `upload`, `dialog`, `screenshot`, `goal`; each takes the arguments of its `safari_<name>` tool plus `tool:"<name>"`), stops at the first failing step, and returns one text report with the page URL and title at the end. An `open` step sets the tab for the steps after it, and the last line names the tab the final step used. A stopped `goal` ends with `[page: <url> | "<title>" | N control(s) listed]` (and says so when the page is `about:blank`). All steps except `goal` are plain code, no model.
- A `click` step with `answerDialog: accept|dismiss` clicks from a timer and presses the button on the native dialog it raises, so a confirm does not block the batch (it fails if no dialog appears within 5 s).
- `goal` (`goal`, optional `text`, `max_steps` default 6, max 15) is the one model-driven step: each round it lists the visible controls, asks TypeSafe (`jev-latest`, `POST https://api.typesafe.ai/v1/systemone`) whether the goal is met (>= 0.7) and which control is next (>= 0.6), then clicks it or fills a field with `text`. It never invents text, refuses to click delete / remove / merge / pay / purchase / buy / transfer / revoke / deactivate / unsubscribe / publish / send unless the goal names that word, and stops (does not answer) if the click opens a native dialog.
- `goal` needs `TYPESAFE_API_KEY` in the server's environment (Claude Code passes its own env on). It sends the page URL without query, the title, about 600 characters of visible text and the control labels to TypeSafe, never field values and never password inputs. Do not use it on pages whose visible text is secret.
**Debugging `open`**
- `safari_open` waits until the new tab is past its initial `about:blank` and `readyState` is `complete`. Start the server with `SAFARI_MCP_DEBUG=1` to log every poll (ref, elapsed ms, readyState, href) to stderr.
**File uploads**
- Never click a file input or "Upload" button with `safari_click`: that is where a native file dialog would take over. Use `safari_upload files:["/abs/path"]` (mode `input` for an `<input type=file>`, even hidden; `click` with `text:"Upload"` for sites that create the input on click; `drop` with a selector for drop zones). No dialog opens, so it works in the background.
- Files are sent as bytes in 300 KB chunks (max 25 MB each) and become `File` objects set through `DataTransfer`. `~/.ssh`, `~/.aws`, `~/.config`, `.env*`, `*.pem` and similar, also via symlinks, are refused. Sites that check `isTrusted` or read the file through a real picker (File System Access API, which Safari lacks anyway) are not covered.
**Scripts**
- `safari_js` supports `await` (set `timeoutSeconds`). Main frame only: iframes and shadow DOM are invisible.
- A page that navigates mid-script returns "Unexpected result from Safari". Re-run after the page settles (`safari_wait`).
**Secrets**
- Use `safari_extract_to_file` for values shown on a page, so they never enter the conversation. Keep any file you write out of git.
## License
MIT, see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues