Safari MCP Server: The Complete Guide (2026)

TL;DR + what you actually need

Safari MCP is a macOS-only MCP server that automates native Safari rather than Chromium. The short version:

• Install: npx safari-mcp — no hosted endpoint, it runs locally on your Mac as a stdio subprocess of your client.
• Package: safari-mcp on npm, maintained at github.com/achiya-automation/safari-mcp (MIT).
• Two one-time toggles: Safari → Settings → Advanced → “Show features for web developers”, then Develop → “Allow JavaScript from Apple Events”.
• Why anyone picks it: it drives the browser you’re already logged into, stays in the background, and uses roughly 60% less CPU than a Chrome-based server on Apple Silicon.

If you only remember one thing: this is the server you reach for when you want an agent to act as you inside your existing Safari session — authenticated, no fresh profile, no fan noise. The rest of this guide explains the AppleScript design, walks the full install, and is honest about where Chrome DevTools MCP still wins.

What Safari MCP actually does

Every other browser-automation MCP — Playwright, Browserbase, Chrome DevTools — ultimately drives a Chromium instance. On a Mac that means a separate browser process you don’t otherwise use, eating a few hundred megabytes of RAM and warming up the fans, with a fresh profile that knows none of your logins. Safari MCP takes the opposite bet: automate the browser already sitting in your Dock.

Concretely, an agent connected to Safari MCP can open and switch tabs, click and fill forms (including React, Vue, Angular and Svelte forms, via native value setters rather than fake keystrokes), read the page DOM and accessibility tree, run arbitrary JavaScript, take screenshots, inspect network traffic, mock routes, emulate devices, and read or write cookies and local storage. Because it’s your real Safari, anything you’re logged into — Gmail, GitHub, Ahrefs, a banking dashboard — is already authenticated for the agent. No re-login, no cookie injection, no CAPTCHA wall that a clean headless profile would have tripped.

It is maintained by Achiya Automation, lives at github.com/achiya-automation/safari-mcp under the MIT license, and has been written up on freeCodeCamp and HackerNoon. One thing to flag up front: several unrelated projects share the “safari-mcp” name. This guide is about the achiya-automation/safari-mcp package — verify the namespace before you install, since the others differ a lot in tool count and install method.

Why AppleScript + WebKit, not Puppeteer

The interesting engineering choice here is the automation layer. Chrome-based servers talk to the browser over the Chrome DevTools Protocol; Playwright ships its own runtime. Safari MCP instead uses a dual-engine design: a Safari extension when it’s installed (preferred for speed and the hard DOM cases), and AppleScript backed by a persistent Swift helper as an always-available fallback. Around 80% of the tool surface works through AppleScript alone, with no extension and no build step.

The persistent-process detail is what makes this practical rather than slow. Spawning a new osascript per command would be sluggish; instead a single long-running helper stays warm, which the project measures at roughly 5ms per command versus ~80ms for cold spawns. That keeps the snapshot → reason → act loop tight enough for real agent work, and it’s a big part of why the whole thing feels light: there’s no browser to boot and no DevTools Protocol overhead on the wire.

The other half of the “why” is just WebKit. Apple’s own numbers put Safari ahead of Chrome on JavaScript performance and well below it on power draw on Apple Silicon, and driving the engine that’s already resident on the machine avoids running a second rendering stack entirely. The result a user feels is less heat, quieter fans, and an agent that never yanks a window in front of what they’re doing.

Install (macOS)

The base install is genuinely one command. Everything else is granting macOS the permissions it insists on for automating another app — covered in the next section. Prerequisites are just macOS with Safari and Node 18+:

npx safari-mcp

In practice you don’t run that by hand — you point your MCP client at it and the client launches it as a subprocess. The install panel below pulls the exact, copy-paste configuration for each client (Claude Code, Cursor, VS Code, Windsurf and the manual JSON fallback) straight from our catalog, so it stays in sync with how the server is actually shipped. Tap your client’s row, copy the command or JSON, and Safari MCP is registered.

One-line install · safari-mcp

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Before the first run, flip the two Safari developer toggles or every AppleScript-backed tool will error out:

1. Safari → Settings → Advanced → enable Show features for web developers.
2. Safari → Develop → enable Allow JavaScript from Apple Events.

That second toggle is the one people forget; without it the server connects fine but every do JavaScript call fails with an AppleScript error. If you’re comparing browser servers more broadly first, our Chrome DevTools vs Playwright MCP comparison covers the Chromium-based options, and what is MCP explains the protocol if any of this is new.

macOS permissions (the part that trips people up)

Driving one app from another is exactly the kind of thing macOS guards with TCC prompts, so plan for a few one-time approvals. The non-obvious one bites IDE users:

• Automation → Safari. macOS grants this to the parent process that spawns the server — your IDE or terminal, not safari-mcp itself. So approve Automation → Safari for Visual Studio Code, Cursor or Terminal in System Settings → Privacy & Security → Automation. If the dialog never appears, run this once from a terminal that already has permission to force it:

osascript -e 'tell application "Safari" to get URL of current tab of window 1'

• Screen Recording — required for safari_screenshot. Grant it to the same app (Terminal / VS Code).
• Accessibility — only needed for the OS-level safari_native_* tools (native click / keyboard / hover and PDF export). Add the bundled safari-helper binary under System Settings → Privacy & Security → Accessibility.

One sharp edge worth knowing in advance: running npm update changes the helper binary’s code signature, which can silently revoke the Automation grant. If tools start failing with “not authorized” right after an update, re-run the osascript one-liner above to re-grant it.

The optional Safari extension

You can use Safari MCP without the extension — AppleScript covers roughly 80% of the tools out of the box. The extension exists for the cases AppleScript genuinely can’t reach:

• Closed shadow DOM — Reddit’s web components and similar are invisible to AppleScript but fully accessible with the extension.
• Strict CSP sites — the extension can execute in the page’s main world and bypass Content-Security-Policy restrictions that block injected scripts.
• Deep framework state — manipulating React Fiber, ProseMirror and similar editors directly.

The catch: the extension isn’t in the npm package. You clone the repo and build it once with Xcode (a free personal Apple ID is enough for local use), then enable Safari MCP Bridge under Safari → Settings → Extensions. Two friction points to set expectations: building requires Xcode, and Safari’s “Allow Unsigned Extensions” setting resets on every Safari restart, so you re-enable it from the Develop menu after each restart (the extension itself stays installed). If you mostly automate ordinary pages, skip it; if your targets are modern SPAs and rich-text editors, it’s worth the one-time setup.

The tool surface

Safari MCP ships a broad set of tools — comfortably the widest of the Safari-focused servers — grouped into a few families. You don’t call these by hand; the agent picks them. Knowing the shape helps you reason about what’s possible:

The file-upload trick is a nice example of the JavaScript-first philosophy: rather than wrestling a native file dialog, safari_upload_file constructs the upload via a JS DataTransfer object, so no OS dialog ever appears. The same instinct runs through form filling and clicking — events are synthesized in the page, which sidesteps keyboard-layout problems and focus conflicts.

Safari MCP vs Chrome DevTools MCP

This is the comparison most people arrive with, so here’s the honest version using the maintainer’s own published numbers. The headline: Safari MCP wins on logins, CPU and focus; Chrome DevTools MCP wins on auditing.

Read that table as a routing rule, not a winner. Authenticated, repetitive browsing on a Mac you actually use? Safari MCP, every time — it’s cooler, keeps your sessions, and stays out of your way. Need a Lighthouse score or a flame-chart performance trace? That’s Chrome DevTools MCP’s job, and Safari MCP doesn’t pretend otherwise. Plenty of people run both and let the agent pick. For where Chrome DevTools MCP sits against the other Chromium options, see our Chrome DevTools vs Playwright MCP deep dive.

Recipes

Where the “drive my real browser” model earns its keep. All of these assume Safari MCP is registered in your client and you’re already logged into the relevant sites.

Recipe 1 — Pull data from a tool you’re logged into

You want yesterday’s numbers out of an analytics or SEO dashboard that has no usable API and sits behind SSO. A headless scraper hits the login wall; Safari MCP doesn’t, because you’re already signed in. Ask the agent to open the report, read the table with safari_extract_tables, and hand back the rows. No credentials in config, no cookie juggling.

Recipe 2 — A QA loop on your staging site

Point the agent at a staging URL and have it walk a flow: navigate, fill the form with safari_fill (React-aware, so the framework actually registers the input), submit, then safari_snapshot the result and screenshot any failure. Because it runs in the background, you keep coding in the same window while the loop runs.

Recipe 3 — Reproduce a bug against mocked network

Use safari_mock_route to force an endpoint to return an error or an empty payload, then drive the UI to confirm it degrades gracefully. This is the kind of failure-path testing that’s awkward to set up by hand and that the Chrome DevTools server can’t do at all.

Recipe 4 — Background research while you work

Hand the agent a list of pages to read and summarize — docs, changelogs, a competitor’s pricing page. It opens each in a tab by index, reads with safari_read_page, and never pulls focus. You get the digest without your screen flickering through ten tab switches.

Honest tradeoffs

No tool is free of sharp edges. The ones worth weighing before you commit:

• macOS only. This is the big one. No Windows, no Linux, no CI box that isn’t a Mac. If your team isn’t all on macOS, a Chromium server is the portable choice.
• No Lighthouse, no performance trace. If web-vitals auditing is your core workflow, Safari MCP is the wrong primary tool — keep Chrome DevTools MCP for that.
• Permission setup is fiddly. The Automation-grant-goes-to-the-parent-process behavior and the per-restart “Allow Unsigned Extensions” reset are real friction the first time. They’re one-time once you know them, but they will cost you ten confused minutes if you don’t.
• It’s your real browser. The feature is also the caution: an agent acting in your authenticated Safari can do anything you can. Scope what you let it do, and don’t point it at destructive actions in production accounts unsupervised.

Troubleshooting

FAQ

Sources

• Safari MCP repository & README: github.com/achiya-automation/safari-mcp (MIT, maintained by Achiya Automation)
• NPM package: npmjs.com/package/safari-mcp
• freeCodeCamp — How to Connect Your AI Coding Agent to a Browser on macOS: freecodecamp.org
• HackerNoon — Reverse-Engineering React, Shadow DOM and CSP to automate Safari: hackernoon.com
• Catalog entry: mcp.directory/servers/safari-mcp