🦁 Safari MCP

The browser for your coding agent.

Your real Safari, logged in — no Chrome, no heat, no headless.

Install in VS Code · VS Code Insiders · Install in Cursor

97 tools · No Chrome/Puppeteer/Playwright needed · ~5ms per command · 60% less CPU than Chrome

Quick Start · All 97 Tools · Examples · Why Safari MCP? · Architecture · Changelog

❌ Without Safari MCP

Your AI agent needs to browse. So it either:

• Spins up Chromium via Playwright — with no logins, no cookies, no sessions
• Uses Chrome DevTools MCP — and melts your fan running a second browser
• Relies on headless scrapers — blocked by Cloudflare, reCAPTCHA, and bot detection

✅ With Safari MCP

Your AI drives the Safari you're already logged into — Gmail, GitHub, Ahrefs, Slack, banking.

Native WebKit. ~60% less CPU. Background operation. 97 tools. One npx command. macOS only.

📰 Featured on freeCodeCamp: How to Connect Your AI Coding Agent to a Browser on macOS · HackerNoon: Reverse-Engineering React, Shadow DOM, and CSP

🍎 Apple shipped an official Safari MCP (July 2026 — Safari Technology Preview 247+ and the Safari 27 beta). It's built on safaridriver for isolated debugging sessions. safari-mcp drives the real Safari you're already logged into — on the stable Safari that ships with macOS today, with 97 tools. See the full comparison below.

---

Highlights

• 97 tools — navigation, clicks, forms, screenshots, network, storage, accessibility, and more
• Zero heat — native WebKit on Apple Silicon, ~60% less CPU than Chrome
• Your real browser — keeps all logins, cookies, sessions (Gmail, GitHub, Ahrefs, etc.)
• Background operation — Safari stays in the background, no window stealing
• No browser dependencies — no Puppeteer, no Playwright, no WebDriver, no Chrome
• Persistent process — reuses a single osascript process (~5ms per command vs ~80ms)
• Framework-compatible — React, Vue, Angular, Svelte form filling via native setters

---

In users' own words

Not solicited testimonials — quotes lifted from the public issue tracker, each linked to the thread it came from.

"I run multiple Pi sessions/subagents against my normal Safari profile in parallel. Sharing its cookies and logins is intentional." — @maxim, on running concurrent agents against a real browser

"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." — @turner-moore, on why the guards refuse to touch your tabs

"Direct local validation from the package: Safari MCP doctor 6/6." — @jrepp, who found and fixed a queue-alignment bug in the focus helper

---

Quick Start

Prerequisites

• macOS (any version with Safari)
• Node.js 20+
• Safari → Settings → Advanced → Show features for web developers ✓
• Safari → Develop → 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:

claude mcp add safari -- npx safari-mcp

Or edit ~/.mcp.json:

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

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

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

Restart Claude Desktop after saving.

One-click: Install in Cursor

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

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

One-click: Install in VS Code

Or edit .vscode/mcp.json:

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

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

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

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

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

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

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

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

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

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

• Name: safari
• Command: npx
• Args: safari-mcp

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

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

brew install achiya-automation/tap/safari-mcp

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

---

Usage Workflow

The recommended pattern for AI agents using Safari MCP:

1. safari_snapshot        → Get page state (accessibility tree)
2. safari_click/fill/...  → Interact with elements by ref
3. safari_snapshot        → Verify the result

Element targeting — tools accept multiple targeting strategies:

Strategy	Example	Best for
CSS selector	#login-btn, .submit	Unique elements
Visible text	"Sign In", "Submit"	Buttons, links
Coordinates	x: 100, y: 200	Canvas, custom widgets
Ref from snapshot	ref: "e42"	Any element from accessibility tree

Tip: Start with safari_snapshot to get element refs, then use refs for precise targeting. This is faster and more reliable than CSS selectors.

---

Running several agents at once

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:

SAFARI_MCP_HTTP=1 SAFARI_MCP_HTTP_PORT=9225 npx safari-mcp

Then point every client at it:

{ "mcpServers": { "safari-mcp": { "type": "http", "url": "http://127.0.0.1:9225/mcp" } } }

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.

Two properties make this safe rather than merely tidy:

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

• 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:

  Tab tracking lost — refusing to fall back to "current tab of window"
  (would target the user's active tab). Call safari_new_tab to reopen.
  

This also drops process count sharply: ~17 node processes for 17 concurrent sessions becomes 1.

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.

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, 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 (a pi extension by @maxim, born out of #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.

---

Acting on a tab you already have open

By default the server touches only tabs it opened itself. Point it at one of yours and it refuses:

Tab safety: refusing "click" — current tab (https://mail.example.com/inbox) was not
opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.

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:

{ "tabIndex": 3, "safeUrl": "https://mail.example.com/inbox", "note": "(user tab, opted-in)" }

What the flag deliberately does not do:

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

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.

---

Environment variables

Variable	Default	What it does
SAFARI_MCP_HTTP	off	Run one shared HTTP daemon instead of a process per client (see above).
SAFARI_MCP_HTTP_PORT	9225	Port for that daemon.
SAFARI_PROFILE	unset	Bind sessions to a named Safari profile. Unset = your ordinary windows.
SAFARI_MCP_ALLOW_USER_TABS	off	Let safari_switch_tab adopt a tab you already had open, instead of refusing it (see below).
SAFARI_MCP_RAISE_ON_NAVIGATE	off	Let navigation bring Safari to the front, and stop the focus guard from putting your previous app back.
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.
SAFARI_MCP_KEEPALIVE_TAB	off	Keep one daemon-served page open in the profile window so Safari never parks the extension worker between commands.
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.

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.

---

Tools (97)

Navigation (4)

Tool	Description
safari_navigate	Navigate to URL (auto HTTPS, wait for load)
safari_go_back	Go back in history
safari_go_forward	Go forward in history
safari_reload	Reload page (optional hard reload)

Page Reading (3)

Tool	Description
safari_read_page	Get title, URL, and text content
safari_get_source	Get full HTML source
safari_navigate_and_read	Navigate + read in one call

Click & Interaction (6)

Tool	Description
safari_click	Click by CSS selector, visible text, or coordinates
safari_double_click	Double-click (select word, etc.)
safari_right_click	Right-click (context menu)
safari_hover	Hover over element
safari_click_and_wait	Click + wait for navigation
safari_click_and_read	Click then return the updated page — saves a round-trip (React Router + full loads)

Form Input (11)

Tool	Description
safari_fill	Fill input (React/Vue/Angular compatible)
safari_clear_field	Clear input field
safari_select_option	Select dropdown option
safari_fill_form	Batch fill multiple fields
safari_fill_and_submit	Fill form + submit in one call
safari_type_text	Type real keystrokes (JS-based, no System Events)
safari_press_key	Press key with modifiers
safari_react_select_set	Set a react-select v5 value via React fiber — bypasses the menu UI
safari_react_select_list_options	List a react-select v5 dropdown's options without opening it
safari_replace_editor	Replace all content in a code editor (Monaco, CodeMirror, Ace, ProseMirror)
safari_verify_state	Verify an editor's framework-level state matches expected — catch stale DOM before Submit

Screenshots & PDF (3)

Tool	Description
safari_screenshot	Screenshot as PNG (viewport or full page)
safari_screenshot_element	Screenshot a specific element
safari_save_pdf	Export page as PDF

Scroll (3)

Tool	Description
safari_scroll	Scroll up/down by pixels
safari_scroll_to	Scroll to exact position
safari_scroll_to_element	Smooth scroll to element

Tab Management (5)

Tool	Description
safari_list_tabs	List all tabs (index, title, URL)
safari_new_tab	Open new tab (background, no focus steal)
safari_close_tab	Close tab
safari_switch_tab	Switch to tab by index
safari_wait_for_new_tab	Wait for a new tab (e.g. OAuth popup) and auto-switch to it

Wait (2)

Tool	Description
safari_wait_for	Wait for element, text, or URL change
safari_wait	Wait for specified milliseconds

JavaScript (1)

Tool	Description
safari_evaluate	Execute arbitrary JavaScript, return result
safari_eval_file	Execute JavaScript read from a file path (avoids huge inline scripts)

Element Inspection (4)

Tool	Description
safari_get_element	Element details (tag, rect, attrs, visibility)
safari_query_all	Find all matching elements
safari_get_computed_style	Computed CSS styles
safari_detect_forms	Auto-detect all forms with field selectors

Accessibility (2)

Tool	Description
safari_accessibility_snapshot	Full a11y tree: roles, ARIA, focusable elements
safari_snapshot	Accessibility tree with ref IDs for every interactive element — preferred way to see page state

Drag & Drop (1)

Tool	Description
safari_drag	Drag between elements or coordinates

File Operations (2)

Tool	Description
safari_upload_file	Upload file via JS DataTransfer (no file dialog!)
safari_paste_image	Paste image into editor (no clipboard touch!)

Dialog & Window (2)

Tool	Description
safari_handle_dialog	Handle alert/confirm/prompt
safari_resize	Resize browser window

Device Emulation (2)

Tool	Description
safari_emulate	Emulate device (iPhone, iPad, Pixel, Galaxy)
safari_reset_emulation	Reset to desktop

Cookies & Storage (11)

Tool	Description
safari_get_cookies	Get all cookies
safari_set_cookie	Set cookie with all options
safari_delete_cookies	Delete one or all cookies
safari_local_storage	Read localStorage
safari_set_local_storage	Write localStorage
safari_delete_local_storage	Delete/clear localStorage
safari_session_storage	Read sessionStorage
safari_set_session_storage	Write sessionStorage
safari_delete_session_storage	Delete/clear sessionStorage
safari_export_storage	Export all storage as JSON (backup/restore sessions)
safari_import_storage	Import storage state from JSON

Clipboard (2)

Tool	Description
safari_clipboard_read	Read clipboard text
safari_clipboard_write	Write text to clipboard

Network (6)

Tool	Description
safari_network	Quick network requests via Performance API
safari_start_network_capture	Start detailed capture (fetch + XHR)
safari_network_details	Get captured requests with headers/timing
safari_clear_network	Clear captured requests
safari_mock_route	Mock network responses (intercept fetch/XHR)
safari_clear_mocks	Remove all network mocks

Console (4)

Tool	Description
safari_start_console	Start capturing console messages
safari_get_console	Get all captured messages
safari_clear_console	Clear captured messages
safari_console_filter	Filter by level (log/warn/error)

Performance (2)

Tool	Description
safari_performance_metrics	Navigation timing, Web Vitals, memory
safari_throttle_network	Simulate slow-3g/fast-3g/4g/offline

Data Extraction (4)

Tool	Description
safari_extract_tables	Tables as structured JSON
safari_extract_meta	All meta: OG, Twitter, JSON-LD, canonical
safari_extract_images	Images with dimensions and loading info
safari_extract_links	Links with rel, external/nofollow detection

Advanced (7)

Tool	Description
safari_override_geolocation	Override browser geolocation
safari_list_indexed_dbs	List IndexedDB databases
safari_get_indexed_db	Read IndexedDB records
safari_css_coverage	Find unused CSS rules
safari_analyze_page	Full page analysis in one call
safari_doctor	Diagnose the macOS permission + daemon chain (Apple Events, Accessibility, Screen Recording, codesign) with per-failure fixes
safari_reload_extension	Hot-reload the Safari MCP Bridge extension without a manual toggle

Automation (1)

Tool	Description
safari_run_script	Run multiple actions in a single call (batch)

Native Input — CGEvent (4)

Tool	Description
safari_native_click	OS-level mouse click (CGEvent, isTrusted: true) — bypasses WAF/bot detection when safari_click is blocked (405/403)
safari_native_hover	OS-level cursor hover — triggers real :hover/mouseenter for tooltips and obfuscated UIs
safari_native_type	Insert text via the real paste pipeline — ProseMirror/Slate/Draft.js process it natively so Submit sends real data
safari_native_keyboard	OS-level keypress + modifiers to Safari, no focus steal — reaches React trust-gated handlers (Discord/Slack send)

iOS & WebKit Validation (4)

Tool	Description
safari_inspect_viewport	Validate the <meta name=viewport> tag for iOS Safari (device-width, zoom/WCAG, viewport-fit)
safari_safe_area_insets	Read live safe-area-inset values + viewport-fit / env() usage (notch / Dynamic Island)
safari_check_pwa	Audit iOS "Add to Home Screen" / PWA readiness (apple-touch-icon, manifest, theme-color, splash)
safari_webkit_compat	Check page CSS against this Safari via CSS.supports() — unsupported props, missing -webkit- prefixes, known quirks

---

Security

Safari MCP runs locally on your Mac with minimal attack surface:

Aspect	Detail
Network	No remote connections — all communication is local (stdio + localhost)
Permissions	macOS system permissions required (Screen Recording for screenshots)
Data	No telemetry, no analytics, no data sent anywhere
Extension	Communicates only with the local profile bridges (localhost:9224/9228/9232/9236), validated by Safari
Code	Fully open source (MIT) — audit every line

---

Safari MCP vs Alternatives