Safari MCP

Prerequisites

• macOS (any version with Safari)
• Node.js 18+
• 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 the extension

xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \ -scheme "Safari MCP (macOS)" -configuration Release build

(xcodebuild without a signing identity produces a bundle Safari silently rejects)

APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release -name "Safari MCP.app" -maxdepth 2 | head -1) codesign --sign - --force --deep "$APP_PATH"

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

---

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

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

open "$APP_PATH" ```

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

---

Safari MCP vs Alternatives

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

Troubleshooting

---