convez.ai
MCP Server
erwinzhang7

safari-mcp

erwinzhang7/safari-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Native MCP server to drive Safari on macOS — navigate, click, type, run JS, screenshots, computer-use, file upload, and console/network capture. Zero runtime deps.

Instalação

$npx convez-ai erwinzhang7/safari-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 semanas
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Safari MCP

A native Model Context Protocol server that lets an MCP client (e.g. Claude Code) drive Safari on macOS — navigate, read, click, type, run JS, take screenshots, do screenshot-driven mouse/keyboard control, upload files, and capture console/network traffic. The Safari equivalent of a "browser in your agent," built native with zero runtime dependencies.

Two complementary halves:

  • Native driver (driver/) — a single Swift binary that speaks MCP over stdio and drives Safari via AppleScript (do JavaScript), CoreGraphics (screencapture, CGEvent), and NSPasteboard. Hand-rolled JSON-RPC and WebSocket — no SDK, no ws, no Node.
  • Safari extension (extension/) — a vanilla-JS MV3 extension whose only job is to capture the current site's console + network and stream it to the driver over a loopback WebSocket. Its popup is a small status panel (bridge health, capture state, event counts, and per-site permission management). No API key, no embedded chat.
MCP client ──stdio(MCP)──▶ safari-mcp (Swift) ──AppleScript/CGEvent──▶ Safari ──▶ pages
                                  ▲
                                  │ ws://127.0.0.1:8787 (console/network telemetry)
                                  │
                       Safari extension (MV3) ──▶ status + permission popup

Why this shape

Safari's extension model is hostile to silent automation (per-site prompts, sandboxing, unsigned-extension resets). So the heavy lifting is native (AppleScript + CoreGraphics), which needs only one-time macOS permission grants — and the extension stays tiny, doing the one thing native automation can't easily do: capture console/network from inside the page. See RESEARCH.md for the verified platform constraints and PLAN.md for the design.

Requirements

  • macOS with Safari, and Xcode (for building/installing the extension).
  • A Swift toolchain (swift), Python 3, and Node (for the test runners only).
  • A code-signing identity. A stable identity (Apple Development or Developer ID) is strongly recommended so macOS permission grants persist across rebuilds.

Build & install

Quick start (build the driver and register it globally in one command):

# Optional but recommended: a stable signing identity so macOS permission grants persist.
export SMCP_SIGN_IDENTITY="Apple Development: you@example.com"
make install          # builds + signs the driver, registers it as a global MCP server
make build-extension  # generates the Xcode project; then build/run it once (step 2 below)

Then restart your MCP client and finish the Safari steps below. The two halves in detail:

1. Driver

# Signs with $SMCP_SIGN_IDENTITY (defaults to ad-hoc "-"). Set it to a stable identity so the
# macOS Automation grant sticks across rebuilds, e.g. SMCP_SIGN_IDENTITY="Apple Development: you@example.com".
./scripts/build-driver.sh release
# Register it (the script prints the exact binary path; `make install` does this for you):
claude mcp add safari --scope user -- "$(cd driver && swift build -c release --show-bin-path)/safari-mcp"

One-time macOS grants (per the signing identity):

  • Approve the Automation prompt for Safari the first time a tool runs (System Settings ▸ Privacy & Security ▸ Automation).
  • Safari ▸ Settings ▸ Advanced ▸ Show features for web developers, then Develop ▸ Allow JavaScript from Apple Events.
  • For safari_screenshot: Screen Recording permission (prompted on first use).
  • For safari_computer with real: true: Accessibility permission (prompted on first use).

2. Extension

./scripts/build-extension.sh             # converts extension/ → an Xcode project under app/
open app/SafariMCP/SafariMCP.xcodeproj

In Xcode: set your signing Team on both targets (a free Apple ID works), then Product ▸ Run to install. In Safari: Develop ▸ Allow Unsigned Extensions (resets each launch unless the extension is signed by a real Developer ID), Settings ▸ Extensions ▸ enable Safari MCP, then grant a site capture via the toolbar popup. extension/ is the source of truth; app/ is a regenerated build artifact (gitignored) — re-run build-extension.sh after editing extension/.

Driver changes require a fresh MCP-client session to load (the server set is fixed at session start). Extension changes hot-reload in Safari, but reinstalling the app can disable the extension — re-enable it in Settings ▸ Extensions if so.

Per-site permissions

Read-only tools (list tabs, read page text/DOM, screenshots, console/network) work anywhere. Anything that acts on a page or runs JS (click, type, set value, scroll, run_js, navigate, reload, computer-use input, storage writes, file upload) is gated per origin:

  • The first time the agent acts on an unauthorized site, the driver pops a native Allow / Deny dialog. Allow adds the origin to a persistent allowlist; the agent can never self-authorize.
  • Grant/revoke any time from the extension popup. Capture is folded into the same auth: a site must be allowed before console/network stream.

MCP tools

ToolWhat it does
safari_list_tabsList all tabs across windows (with stable tabIds)
safari_navigateOpen a URL in a tab (waits for load)
safari_new_tab / safari_close_tab / safari_activate_tabTab management (new tabs open in the background)
safari_reload / safari_back / safari_forwardHistory navigation
safari_resize_windowResize a window (responsive testing)
safari_get_page_textVisible page text (innerText)
safari_read_pageSnapshot interactive elements with stable refs
safari_findFind elements by CSS selector or visible text
safari_inspectComputed styles, bounding box, attributes, outerHTML
safari_click / safari_type / safari_set_valueInteract with elements by ref / selector / text
safari_scrollScroll by direction/amount, or a ref/selector into view
safari_wait_forWait for a selector / text / network-idle (with timeout)
safari_run_jsRun arbitrary JS, return its result (escape hatch)
safari_screenshotPNG of a Safari window — works on background/occluded windows
safari_computerScreenshot-driven mouse/keyboard control with an on-page cursor overlay
safari_uploadUpload a local file into a file input / drop zone (no native picker)
safari_clipboardRead/write the macOS clipboard (copy/paste workflows)
safari_storageRead/write localStorage, sessionStorage, cookies
safari_read_console / safari_read_networkCaptured console / network, filterable (needs the extension)
safari_bridge_statusIs the extension connected? how much is buffered?
safari_permissionsList or revoke per-site action permissions

Notes:

  • Most tools take an optional tabId (from safari_list_tabs); omit for the active tab. Tabs in non-front and occluded windows are addressed reliably and driven in the background.
  • safari_computer defaults to DOM-synthesized input dispatched inside the target tab — it works in the background, needs no Accessibility grant, and draws a cursor/click overlay. Set real: true for true OS-level CGEvent input (needs the window frontmost + Accessibility) for sites that reject synthetic events.
  • safari_read_network captures request/response headers and (for JSON/text responses) bodies up to 16KB; sensitive headers are redacted unless includeSecrets: true.

Tests

make test          # runs both self-tests (neither needs Safari)
  • protocol_selftest.py — MCP protocol layer (initialize, tools/list, tools/call, errors).
  • bridge_selftest.mjs — the console/network bridge, with a Node WS client standing in for the extension.

Repo layout

driver/        Swift package — the native MCP driver
extension/     MV3 Safari extension source (the single source of truth)
scripts/       build-driver.sh, build-extension.sh, patch-xcodeproj.py, make-icons.py
app/           generated Xcode project (gitignored build artifact)
PLAN.md        architecture;  RESEARCH.md  verified platform findings

License

Apache License 2.0 — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados