Skip to main content
Glama

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).

Related MCP server: safari-devtools-mcp

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers