safari-mcp
Provides background browser-automation support for editing Google Docs, including clicking visual lines, placing or selecting text, replacing/inserting text through Docs' hidden input pipeline, navigating with page-scoped key presses, and locating headings via the document outline.
Drives the user's real logged-in Safari through AppleScript/osascript, providing tools for tab management, opening URLs, running JavaScript, reading pages, inspecting and clicking elements, editing text fields, uploading files, handling native dialogs, waiting, extracting data to files, taking screenshots, and running batched browser-automation steps in a background agent window.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_clicksends 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|noneto override;x/yfor a point). On Google Docsline: nclicks 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 (findsubstring, 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: truereplaces what a previous click/select left. On Docs the target isline: nor 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_pressis page-scoped (acceptsmodifiers): 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_keykeeps its schema but is guarded: needsallowForeground: trueevery call; refused within 3 s of the user's last keyboard/mouse activity; refused on Google Docs/Sheets/Slides; command/control combos needallowShortcut: trueand 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_clickdefault coordinates changed from 0,0 to the element centre;safari_typeon a contenteditable now replaces only that element's content (it used to select the whole editor).safari_batchacceptsset_caret,select_textandedit_textsteps.Docs limits: one visual line per
line;findis 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.mjsmacOS 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_tabrequires an explicit tab.Secrets: use
safari_extract_to_fileso values go page -> file (mode 600) and never into the conversation.
Tips
Tabs
Agent-window tabs have refs
agent:<n>(returned bysafari_open, listed bysafari_tabs). New tabs append at the end, so a ref stays valid until a tab before it is closed. Your own windows are listed aswindow:tab, which shift whenever you reorder windows; preferurl:/title:for them.safari_open mode=same_tabnavigates the agent window's current tab unless you passtab:.safari_screenshotandsafari_select_tabmake a tab current, so passtab:to avoid overwriting an unrelated tab.safari_opendefault (new_tab) does not change what screenshots show; useforeground: trueto 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 withsafari_read/safari_screenshot/safari_elements. If a dropdown does not open, focus it and trysafari_press(Down,Enter);safari_native_keyis the last resort.safari_native_key(needsallowForeground: 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 keystrokesmeans Accessibility is not granted to the calling app.safari_typewithtext:resolves a label or wrapper to its input. If that fails, passselector:(list inputs withsafari_elements selector:"input"). Generated ids are only stable within one page view, so look them up each time.safari_click text:"Save" exact:true: withoutexact, "Save" also matches "Save as draft" and similar. Several dialogs can stack, so list candidates withsafari_elementsfirst.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_jstime out (the error says so). Usesafari_dialog:action: readshows the message and buttons (No dialog is openotherwise),acceptpresses OK/Leave (text:fills aprompt()first),dismisspresses 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 itssafari_<name>tool plustool:"<name>"), stops at the first failing step, and returns one text report with the page URL and title at the end. Anopenstep sets the tab for the steps after it, and the last line names the tab the final step used. A stoppedgoalends with[page: <url> | "<title>" | N control(s) listed](and says so when the page isabout:blank). All steps exceptgoalare plain code, no model.A
clickstep withanswerDialog: accept|dismissclicks 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, optionaltext,max_stepsdefault 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 withtext. 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.goalneedsTYPESAFE_API_KEYin 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_openwaits until the new tab is past its initialabout:blankandreadyStateiscomplete. Start the server withSAFARI_MCP_DEBUG=1to 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. Usesafari_upload files:["/abs/path"](modeinputfor an<input type=file>, even hidden;clickwithtext:"Upload"for sites that create the input on click;dropwith 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
Fileobjects set throughDataTransfer.~/.ssh,~/.aws,~/.config,.env*,*.pemand similar, also via symlinks, are refused. Sites that checkisTrustedor read the file through a real picker (File System Access API, which Safari lacks anyway) are not covered.
Scripts
safari_jssupportsawait(settimeoutSeconds). 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_filefor 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Automate any website: discover, run and create browser scripts that work behind logins.
Related MCP Servers
- AlicenseBqualityAmaintenanceNative Safari browser automation for AI agents. 80 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.981,008 npm244MIT
- AlicenseAqualityDmaintenanceLets your coding agent control and inspect a live Safari browser on macOS. Provides access to Safari DevTools for debugging, automation, and testing.4951 npm3MIT
- AlicenseAqualityCmaintenanceEnables Claude and other MCP clients to control Safari on macOS, opening tabs, reading pages, clicking, filling forms, pressing keys, running JavaScript, and taking screenshots in the user's real signed-in browser.14MIT
- AlicenseBqualityCmaintenanceEnables AI agents to control the user's real Safari on macOS, reading pages, taking screenshots, clicking, typing, and recording GIFs, with a per-host read-only policy and prompt-injection safeguards.21MIT