MCPSafari

What is MCPSafari about?

MCPSafari provides a native Safari MCP server that lets any MCP‑compatible client (Claude Code, Codex, Cursor, etc.) drive the user's actual Safari browser. The agent works with existing sessions, allowing access to signed‑in sites, cookies, and local history without the need for a headless browser.

How to use MCPSafari?

1. Install the server via Homebrew:

   brew trust epistates/tap
   brew install --cask epistates/tap/mcp-safari
   

   Open the installed MCPSafari.app once, enable the MCPSafari Extension in Safari, and grant site access.
2. Connect a client (example for Claude Code):

   claude mcp add --scope user mcp-safari mcp-safari
   

   Or for Codex CLI:

   codex mcp add mcp-safari -- mcp-safari
   

3. Issue prompts to the agent, e.g., “Open example.com, read the heading, and capture a screenshot.”
4. Use mcp-safari doctor to verify the installation.

Key Features of MCPSafari

• Leverages real Safari session – retains logins, cookies, and browsing history.
• Multiple targeting methods – locate elements by UID (snapshot), CSS selector, visible text, or screen coordinates.
• Native interaction – typing, key presses, hover, and drag‑and‑drop performed with Safari in the foreground and Accessibility permission.
• Rich diagnostics – capture console logs, network activity, and save screenshots without flooding the model context.
• Swift + Manifest V3 extension – built for macOS 14+ / Safari 17+, no runtime dependencies beyond the OS.
• Background DOM tasks – synthetic input runs headlessly; native input requires Safari front‑most.

Use Cases

• QA automation: Validate forms, menus, and drag‑and‑drop on the exact browser version your users see.
• Content scraping with authentication: Access member‑only pages, extract data, and return structured results.
• End‑to‑end testing for React/SPA apps: Use setters that update component state, then verify UI changes.
• Assistive AI agents: Enable Claude, Cursor, or other agents to perform web‑based workflows on behalf of the user.
• Debugging & monitoring: Record console output, network timings, and visual snapshots for post‑run analysis.

FAQ

Q: Which macOS / Safari versions are required? A: macOS 14 (Sonoma) or later with Safari 17+.

Q: Do I need Xcode? A: Only if you want to build from source; the Homebrew cask provides a pre‑built binary.

Q: Why does Safari need to be in front for some actions? A: Native input (real typing, hover, drag) relies on macOS Accessibility APIs that only work when the target window is active.

Q: How is data privacy handled? A: Tool results are sent to the MCP client; refer to SECURITY.md for details on redaction, permissions, and what data may be exposed.

Q: What if the server fails to start? A: Run mcp-safari doctor for diagnostics, ensure the extension is enabled, and verify the Accessibility permission is granted.

Q: Can I run multiple MCP servers simultaneously? A: Yes, each server runs on its own port; configure additional instances in the client’s MCP settings.

MCPSafari: Your favorite browser, ready for agents

A native Safari MCP server for your real, logged-in Safari on macOS. Works with any MCP-compatible client, including Claude Code, Codex, Cursor, OpenCode, and oh-my-pi.

Your agent starts with your existing logins, cookies, and history. Open a signed-in page and get to work.

• Test your site in Safari. Let your agent check forms, menus, and drag-and-drop in the browser your Safari users will see.
• Target elements by UID (from a snapshot), CSS, text, or coordinates. Fill React forms with setters that update application state.
• Check what happened. Read console and network activity, and save screenshots to disk for review without filling the agent's context with image data.
• Run DOM tasks in the background. Native typing, key presses, hover, and drag need Safari in front and Accessibility permission.

QA on real sites has shaped the tools, including fixes for menus that ignored clicks and drop zones that missed files.

Built with Swift and a Manifest V3 Safari extension. Requires macOS 14+ and Safari 17+. Xcode is only needed to build from source.

Quick start

1. Install

brew trust epistates/tap
brew install --cask epistates/tap/mcp-safari

brew trust is needed once: installing a cask auto-trusts the cask, but not the mcp-safari-server formula it depends on, and without it the install stops at Refusing to load formula epistates/tap/mcp-safari-server from untrusted tap.

Open MCPSafari.app once so Safari picks up the extension, then enable MCPSafari Extension in Safari → Settings → Extensions. Grant access to the sites you want your agent to use.

Homebrew installs the published release. This README and the tool reference describe main, which may include unreleased features. Check Releases for your version.

2. Connect your client

For Claude Code:

claude mcp add --scope user mcp-safari mcp-safari

For Codex CLI:

codex mcp add mcp-safari -- mcp-safari

Start a new client session after adding the server. For Claude Desktop, Cursor, and other clients, see client configuration.

3. Try it

Ask your agent:

Open example.com in a new Safari tab, read the page heading, and take a screenshot.

The heading should be “Example Domain”. If the connection fails, see troubleshooting. On versions that include it, mcp-safari doctor checks the installation without changing it.

Before you use it

Your agent acts in your existing browser session. It can access signed-in pages where you allow the extension. Tool results go to your MCP client and may be sent to its model provider; see browser access and data.

Background DOM tasks do not need native input. For hover styling, real keyboard events, and native drag, Safari must be in front. Native hover and drag move your pointer, so leave the mouse alone while they run. See synthetic and native input.

Console and network capture have limits. Pages can alter the captured data, and resource timings do not include HTTP status or headers. See debugging.

Documentation

• Setup and troubleshooting: manual installation, client configuration, ports, and diagnostics.
• Tools and usage: tool list, targeting, forms, uploads, waits, and batches.
• Development: source builds, tests, and architecture.
• Security: permissions, redaction, and vulnerability reporting.
• Changelog and releases.

License

MIT