Safari MCP

Created By
achiya-automation2 months ago
Native Safari browser automation for AI agents — 80 tools via AppleScript, zero Chrome overhead, keeps logins, runs silently. macOS only.
Overview

🦁 Safari MCP

The only MCP server for Safari — native browser automation for AI agents.

License: MIT GitHub release Node.js macOS MCP CI npm downloads GitHub stars achiya-automation/safari-mcp MCP server

80 tools · Zero dependencies · ~5ms per command · 60% less CPU than Chrome

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

Safari MCP Demo


TL;DR: Use your real Safari with all your logins, cookies, and sessions. No headless browsers, no Chrome, no Puppeteer. Just pure AppleScript + JavaScript running natively on macOS — 60% less CPU/heat on Apple Silicon.

🤔 Why not just use Playwright or Chrome DevTools MCP?
ProblemSafari MCP Solution
Chrome DevTools MCP heats up your MacNative WebKit — ~60% less CPU
Playwright launches a new browser without your loginsUses your real Safari with all sessions
Puppeteer requires Chrome + debug portZero dependencies — just AppleScript
Headless browsers can't access your authenticated sessionsGmail, GitHub, Slack — already logged in
Browser automation steals window focusSafari stays in background, never interrupts

Highlights

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

Quick Start

Prerequisites

  • macOS (any version with Safari)
  • Node.js 18+
  • Safari → Settings → Advanced → Show features for web developers
  • Safari → Develop → Allow JavaScript from Apple Events

Install

Option A — npm (recommended):

npm install -g safari-mcp

Option B — Homebrew:

brew install achiya-automation/tap/safari-mcp

Option C — from source:

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

Configure

Add to your MCP client config:

Claude Code (~/.mcp.json)
{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": ["/path/to/safari-mcp/index.js"]
    }
  }
}
Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": ["/path/to/safari-mcp/index.js"]
    }
  }
}
Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": ["/path/to/safari-mcp/index.js"]
    }
  }
}
Windsurf / VS Code + Continue
{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": ["/path/to/safari-mcp/index.js"]
    }
  }
}

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:

StrategyExampleBest for
CSS selector#login-btn, .submitUnique elements
Visible text"Sign In", "Submit"Buttons, links
Coordinatesx: 100, y: 200Canvas, custom widgets
Ref from snapshotref: "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.


Tools (80)

ToolDescription
safari_navigateNavigate to URL (auto HTTPS, wait for load)
safari_go_backGo back in history
safari_go_forwardGo forward in history
safari_reloadReload page (optional hard reload)

Page Reading (3)

ToolDescription
safari_read_pageGet title, URL, and text content
safari_get_sourceGet full HTML source
safari_navigate_and_readNavigate + read in one call

Click & Interaction (5)

ToolDescription
safari_clickClick by CSS selector, visible text, or coordinates
safari_double_clickDouble-click (select word, etc.)
safari_right_clickRight-click (context menu)
safari_hoverHover over element
safari_click_and_waitClick + wait for navigation

Form Input (7)

ToolDescription
safari_fillFill input (React/Vue/Angular compatible)
safari_clear_fieldClear input field
safari_select_optionSelect dropdown option
safari_fill_formBatch fill multiple fields
safari_fill_and_submitFill form + submit in one call
safari_type_textType real keystrokes (JS-based, no System Events)
safari_press_keyPress key with modifiers

Screenshots & PDF (3)

ToolDescription
safari_screenshotScreenshot as PNG (viewport or full page)
safari_screenshot_elementScreenshot a specific element
safari_save_pdfExport page as PDF

Scroll (3)

ToolDescription
safari_scrollScroll up/down by pixels
safari_scroll_toScroll to exact position
safari_scroll_to_elementSmooth scroll to element

Tab Management (4)

ToolDescription
safari_list_tabsList all tabs (index, title, URL)
safari_new_tabOpen new tab (background, no focus steal)
safari_close_tabClose tab
safari_switch_tabSwitch to tab by index

Wait (2)

ToolDescription
safari_wait_forWait for element, text, or URL change
safari_waitWait for specified milliseconds

JavaScript (1)

ToolDescription
safari_evaluateExecute arbitrary JavaScript, return result

Element Inspection (4)

ToolDescription
safari_get_elementElement details (tag, rect, attrs, visibility)
safari_query_allFind all matching elements
safari_get_computed_styleComputed CSS styles
safari_detect_formsAuto-detect all forms with field selectors

Accessibility (1)

ToolDescription
safari_accessibility_snapshotFull a11y tree: roles, ARIA, focusable elements

Drag & Drop (1)

ToolDescription
safari_dragDrag between elements or coordinates

File Operations (2)

ToolDescription
safari_upload_fileUpload file via JS DataTransfer (no file dialog!)
safari_paste_imagePaste image into editor (no clipboard touch!)

Dialog & Window (2)

ToolDescription
safari_handle_dialogHandle alert/confirm/prompt
safari_resizeResize browser window

Device Emulation (2)

ToolDescription
safari_emulateEmulate device (iPhone, iPad, Pixel, Galaxy)
safari_reset_emulationReset to desktop

Cookies & Storage (10)

ToolDescription
safari_get_cookiesGet all cookies
safari_set_cookieSet cookie with all options
safari_delete_cookiesDelete one or all cookies
safari_local_storageRead localStorage
safari_set_local_storageWrite localStorage
safari_delete_local_storageDelete/clear localStorage
safari_session_storageRead sessionStorage
safari_set_session_storageWrite sessionStorage
safari_delete_session_storageDelete/clear sessionStorage
safari_export_storageExport all storage as JSON (backup/restore sessions)
safari_import_storageImport storage state from JSON

Clipboard (2)

ToolDescription
safari_clipboard_readRead clipboard text
safari_clipboard_writeWrite text to clipboard

Network (6)

ToolDescription
safari_networkQuick network requests via Performance API
safari_start_network_captureStart detailed capture (fetch + XHR)
safari_network_detailsGet captured requests with headers/timing
safari_clear_networkClear captured requests
safari_mock_routeMock network responses (intercept fetch/XHR)
safari_clear_mocksRemove all network mocks

Console (4)

ToolDescription
safari_start_consoleStart capturing console messages
safari_get_consoleGet all captured messages
safari_clear_consoleClear captured messages
safari_console_filterFilter by level (log/warn/error)

Performance (2)

ToolDescription
safari_performance_metricsNavigation timing, Web Vitals, memory
safari_throttle_networkSimulate slow-3g/fast-3g/4g/offline

Data Extraction (4)

ToolDescription
safari_extract_tablesTables as structured JSON
safari_extract_metaAll meta: OG, Twitter, JSON-LD, canonical
safari_extract_imagesImages with dimensions and loading info
safari_extract_linksLinks with rel, external/nofollow detection

Advanced (5)

ToolDescription
safari_override_geolocationOverride browser geolocation
safari_list_indexed_dbsList IndexedDB databases
safari_get_indexed_dbRead IndexedDB records
safari_css_coverageFind unused CSS rules
safari_analyze_pageFull page analysis in one call

Automation (1)

ToolDescription
safari_run_scriptRun multiple actions in a single call (batch)

Security

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

AspectDetail
NetworkNo remote connections — all communication is local (stdio + localhost)
PermissionsmacOS system permissions required (Screen Recording for screenshots)
DataNo telemetry, no analytics, no data sent anywhere
ExtensionCommunicates only with localhost:9224, validated by Safari
CodeFully open source (MIT) — audit every line

Safari MCP vs Alternatives

FeatureSafari MCPChrome DevTools MCPPlaywright MCP
CPU/Heat🟢 Minimal🔴 High🟡 Medium
Your logins✅ Yes✅ Yes❌ No
macOS native✅ WebKit❌ Chromium❌ Chromium/WebKit
DependenciesNoneChrome + debug portPlaywright runtime
Tools80~30~25
File uploadJS (no dialog)CDPPlaywright API
Image pasteJS (no clipboard)CDPPlaywright API
Focus steal❌ Background❌ Background❌ Headless
Network mocking
Lighthouse
Performance trace

Tip: Use Safari MCP for daily browsing tasks (95% of work) and Chrome DevTools MCP only for Lighthouse/Performance audits.

Safari MCP Servers Comparison

Featuresafari-mcpMCPSafarisafari-mcp-server
Tools8023~10
LicenseMITNoneMIT
Installnpm / HomebrewBinarynpm
Storage (cookies, localStorage)10 toolsNoneNone
Data extraction (tables, links)5 toolsNoneNone
Network mockingYesNoNo
Device emulationYesNoNo
File upload (no dialog)YesNoNo
PDF exportYesNoNo
Console capture4 tools1No
Performance metricsYesNoNo
Fallback engineDual (Extension + AppleScript)Extension onlyWebDriver

Architecture

Safari MCP uses a dual-engine architecture — the Extension is preferred for speed and advanced capabilities, with AppleScript as an always-available fallback:

Claude/Cursor/AI Agent
        ↓ MCP Protocol (stdio)
   Safari MCP Server (Node.js)
        ↓                    ↓
   Extension (HTTP)     AppleScript + Swift daemon
   (~5-20ms/cmd)        (~5ms/cmd, always available)
        ↓                    ↓
   Content Script       do JavaScript in tab N
        ↓                    ↓
   Page DOM ←←←←←←←←←← Page DOM

Key design decisions:

  • Dual engine with automatic fallback — Extension is preferred; if not connected, AppleScript handles everything seamlessly
  • Persistent Swift helper — one long-running process instead of spawning per command (16x faster)
  • Tab-indexed operations — all JS runs on a specific tab by index, never steals visual focus
  • JS-first approach — typing, clicking, file upload all use JavaScript events (no System Events keyboard conflicts)
  • No activate — Safari is never brought to foreground

Safari Extension (Optional)

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:

What the Extension Adds

CapabilityWith ExtensionAppleScript Only
Closed Shadow DOM (Reddit, Web Components)✅ Full access❌ Invisible
Strict CSP sites✅ Bypasses via MAIN world❌ Often blocked
React/Vue/Angular state manipulation✅ Deep (Fiber, ProseMirror)⚠️ Basic
Loading state detection (spinners, skeletons)✅ Smart detection❌ No
Dialog handling (alert/confirm)✅ Only AppleScript
Native OS-level click (CGEvent)✅ Only AppleScript
PDF export✅ Only AppleScript

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

Installing the Extension

The extension requires a one-time build with Xcode (free, included with macOS):

Prerequisites: Xcode (install from App Store — free)

# 1. Build the extension app
cd safari-mcp
xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
  -scheme "Safari MCP (macOS)" -configuration Release build

# 2. Find and open the built app
open ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release/Safari\ MCP.app

Then in Safari:

  1. Safari → Settings → Advanced → enable Show features for web developers
  2. Safari → Develop → Allow Unsigned Extensions (required each Safari restart)
  3. Safari → Settings → Extensions → enable Safari MCP Bridge

The extension connects automatically to the MCP server on port 9224.

Note: "Allow Unsigned Extensions" resets every time Safari restarts. You'll need to re-enable it in the Develop menu after each restart. The extension itself stays installed.

Toolbar icon status:

  • ON — connected to MCP server
  • OFF — manually disabled via popup
  • (no badge) — server not running, will auto-reconnect

macOS Permissions

Safari MCP needs these one-time permissions:

PermissionWhereWhy
JavaScript from Apple EventsSafari → Develop menuRequired for do JavaScript
Screen RecordingSystem Settings → PrivacyRequired for safari_screenshot
AccessibilitySystem Settings → PrivacyRequired for safari_save_pdf only

Troubleshooting

IssueFix
"AppleScript error"Enable "Allow JavaScript from Apple Events" in Safari → Develop
Screenshots emptyGrant Screen Recording permission to Terminal/VS Code
Tab not foundCall safari_list_tabs to refresh tab indices
Hebrew keyboard issuesAll typing uses JS events — immune to keyboard layout
HTTPS blockedsafari_navigate auto-tries HTTPS first, falls back to HTTP
Safari steals focusEnsure you're on latest version — newTab restores your active tab

Works With

Safari MCP works with any MCP-compatible client:

ClientStatus
Claude Code✅ Tested daily
Claude Desktop✅ Tested
Cursor✅ Tested
Windsurf✅ Compatible
VS Code + Continue✅ Compatible

Contributing

PRs welcome! See CONTRIBUTING.md for setup instructions.

The codebase is two files:

  • safari.js — Safari automation layer (AppleScript + JavaScript)
  • index.js — MCP server with tool definitions

Star History

If Safari MCP saved you from Chrome overhead, consider giving it a ⭐

Star History Chart


License

MIT — use it however you want.

Server Config

{
  "mcpServers": {
    "safari-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "safari-mcp"
      ]
    }
  }
}
Project Info
Created At
2 months ago
Updated At
2 months ago
Author Name
achiya-automation
Star
-
Language
-
License
-
Category

Recommend Servers

View All
Gpt Scrambler

2 days ago