Safari MCP

Prerequisites

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

Granting Accessibility to safari-helper (required for `safari_native_*`)

The safari_native_click, safari_native_keyboard and safari_native_hover tools inject OS-level CGEvent events into Safari without stealing focus. macOS requires the underlying helper binary to be approved in Accessibility before those events can reach a non-frontmost window.

1. Open System Settings → Privacy & Security → Accessibility. 2. Click + (unlock with your password if needed). 3. Navigate to the helper binary and add it: - npm global install: $(npm root -g)/safari-mcp/safari-helper - npx / project install: ./node_modules/safari-mcp/safari-helper - From source clone: /path/to/safari-mcp/safari-helper 4. Make sure the toggle next to it is ON.

The postinstall script re-signs the helper with a stable identifier (com.achiya-automation.safari-mcp) so this permission survives future upgrades — without that step, every npm update would silently revoke approval because the binary's adhoc-signed identifier changes per build.

If safari_native_click reports success but the page doesn't react (no isTrusted: true click events fire), the helper is most likely missing this approval. The safari_* (non-native_) tools don't need it.

Install (one command)

npx safari-mcp

That's it — no global install needed. Or install permanently:

npm install -g safari-mcp

Installing the Extension

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

Note for npm users: The xcode/ directory is not included in the npm package. Clone the GitHub repository to build from source.

Prerequisites: Xcode (install from App Store — free)

```bash

2. Build a clean, Apple Development-signed app

Quick Start

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:

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

---

Screenshots & PDF (3)

Configure your MCP client

All clients run Safari MCP the same way — npx safari-mcp. Pick your editor:

<details> <summary><b>Claude Code</b></summary>

claude mcp add safari -- npx safari-mcp

Or edit ~/.mcp.json:

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

<details> <summary><b>Claude Desktop</b></summary>

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

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

Restart Claude Desktop after saving. </details>

<details> <summary><b>Cursor</b></summary>

One-click: Install in Cursor

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

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

<details> <summary><b>VS Code / VS Code Insiders</b></summary>

One-click: Install in VS Code

Or edit .vscode/mcp.json:

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

<details> <summary><b>Windsurf</b></summary>

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

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

<details> <summary><b>Cline</b></summary>

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

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

<details> <summary><b>Continue</b></summary>

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

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

<details> <summary><b>Goose</b></summary>

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

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

<details> <summary><b>LM Studio</b></summary>

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

- Name: safari - Command: npx - Args: safari-mcp </details>

<details> <summary><b>Zed</b></summary>

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

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

<details> <summary><b>Alternative: Homebrew</b></summary>

brew install achiya-automation/tap/safari-mcp

<details> <summary><b>Alternative: from source</b></summary>

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

---

Environment variables

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.

---

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

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

1. Clone the repo (the npm package does not include the Xcode project)

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

5. Open the app (needed once so Safari registers the extension)

open "$APP_PATH" ```

Do not ad-hoc re-sign Safari MCP.app with codesign --deep --sign -. That replaces the Apple Development identity on the wrapper and embedded extension; current Safari can then silently disable or mark the extension as removed. If a previous build was ad-hoc signed, run the clean build command above again.

Alternatively, open xcode/Safari MCP/Safari MCP.xcodeproj directly in Xcode, select your Apple ID under Signing & Capabilities, and click Run. A free personal Apple Developer account is sufficient for local use.

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 first local bridge whose declared Safari profile matches its own. The default bridge ports are 9224, 9228, 9232, and 9236; a single-profile setup normally uses 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

---

Safari MCP vs Alternatives

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

vs Apple's Official Safari MCP (safaridriver)

In July 2026 Apple shipped an official Safari MCP server built on safaridriver — first in Safari Technology Preview 247, and now also in the Safari 27 beta. That's great validation for the category — and it's built for a different job. Apple's server drives an isolated WebDriver automation session for debugging; safari-mcp drives the real Safari you're already logged into.

It has not reached a stable Safari release yet: on macOS 26.5.2 with Safari 26.5.2, safaridriver --help lists --port, --bidi, --enable and --diagnose, and no --mcp (verified 2026-07-23). Check your own machine with safaridriver --help | grep mcp before assuming either way.

When Apple's server is the right pick: you specifically want a clean-room, WebDriver-standard session for compatibility debugging and you already run a preview or beta build. For everything else — daily automation on the browser you're already signed into, on the Safari that shipped with your Mac — safari-mcp is built for exactly that.

Troubleshooting

---