Safari MCP Server

A MCP (Model Context Protocol) server for visual web access through Safari.

Features

• Visual Web Access: Viewport screenshots for visual inspection
• Full Authentication State: Operates on the user's actual Safari session with cookies preserved
• Tab-Aware Targeting: Act operations target a captured working tab, observe operations follow the user's focus
• Viewport Scrolling: Pixel amount or viewport-page index
• Element Inspection: Tag, visibility, attributes, bounding rect for any CSS selector
• Interaction Tools: Click, type, hover, select option
• Wait Conditions: Selector to appear, disappear, or page text to render
• Link Extraction: Anchor links as { text, href } pairs
• Browser History: Back and forward navigation
• Console Error Capture: Two-phase injection during and after page load

Prerequisites

• macOS → System Settings → Desktop & Dock → Windows → "Prefer tabs when opening documents" option must be set to Always
• macOS → System Settings → Privacy & Security → Screen & System Audio Recording → Terminal app must be enabled
• Safari → Settings → Developer → Automation → "Allow JavaScript from Apple Events" option must be enabled

MCP Server Configuration

Add to mcp.json servers configuration:

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["-y", "@axivo/mcp-safari"],
      "env": {
        "SAFARI_WINDOW_HEIGHT": "1600"
      }
    }
  }
}

Environment Variables

All variables are optional:

• SAFARI_PAGE_TIMEOUT - Page load and selector wait timeout, in milliseconds (default: 10000)
• SAFARI_WINDOW_BOUNDS - Browser window margin offset from top-left corner, in pixels (default: 20)
• SAFARI_WINDOW_HEIGHT - Browser window height, in pixels (default: 1024)
• SAFARI_WINDOW_WIDTH - Browser window width, in pixels (default: 1280)

Prompt Examples

• "Open Safari and use status tool for guidelines"
• "Navigate to example.com"
• "Search for example query"
• "Take a screenshot of the current page"
• "Read the page content to understand what's on the page"
• "Click the 'Sign In' button"
• "Type my email into the login form and submit"
• "Refresh the page to see the latest changes"
• "Go back to the previous page"
• "Navigate forward two steps in browser history"
• "Scroll down 500 pixels"
• "Scroll to page 3 of this article"
• "Search for 'Claude AI' and click the first result"
• "List all open browser tabs"
• "Open a new browser tab and go to example.com"
• "Switch to the first browser tab"
• "Close the second browser tab"
• "Inspect the submit button before clicking it"
• "Hover over the Products menu"
• "Choose 'Canada' in the country dropdown"
• "Wait for the loading spinner to disappear"
• "Read all links on this page"

[!NOTE]

The "use status tool" instruction helps Claude pause and process the _meta.usage guidelines before interacting with the browser.

MCP Tools

Call status first at session start to get the runtime state and full tool surface:

• Act tools target a captured working tab
• Observe tools target the front window's current tab

1. click

   • Click an element on the working tab
   • Type: act tool
   • Optional inputs:
     • key (string): Key to press (e.g., Escape, ArrowRight, Enter, Tab)
     • selector (string): CSS selector for the target element
     • text (string): Visible text or aria-label to match
     • wait (string): CSS selector to wait for after click
     • x (number): X coordinate in pixels
     • y (number): Y coordinate in pixels
   • Returns: Result with change detection

2. close

   • Close the working tab
   • Type: act tool

3. execute

   • Execute JavaScript in the working tab
   • Type: act tool
   • Required inputs:
     • script (string): JavaScript code

4. hover

   • Dispatch hover events to reveal hover-triggered UI
   • Type: act tool
   • Optional inputs (one is required):
     • selector (string): CSS selector for the target element
     • text (string): Visible text to match

5. inspect

   • Return element metadata for a CSS selector
   • Type: observe tool
   • Required inputs:
     • selector (string): CSS selector for the target element
   • Optional inputs:
     • index (number): Tab index in the front window
   • Returns: { found, tag, text, visible, disabled, attributes, rect }

6. navigate

   • Navigate the working tab to a URL or through history
   • Type: act tool
   • Optional inputs (url or direction required):
     • direction (string: back or forward)
     • selector (string): CSS selector to wait for after load
     • steps (number, default: 1): Steps for history navigation
     • url (string): URL to navigate to

7. open

   • Open a blank tab as the working target
   • Type: act tool

8. read

   • Get page title, URL, and text or links from a tab
   • Type: observe tool
   • Optional inputs:
     • index (number): Tab index in the front window
     • mode (string: text or links, default: text)
     • selector (string): CSS selector to scope extraction

9. refresh

   • Refresh the working tab
   • Type: act tool
   • Optional inputs:
     • hard (boolean, default: false): Bypass cache
     • selector (string): CSS selector to wait for after reload

10. screenshot

    • Capture the Safari window, an element, the full page, or the screen
    • Type: observe tool
    • Optional inputs:
      • display (number): Display index for screen mode, 1-based, defaults to the main display
      • mode (string: element, page, screen, window, default: window): Capture mode
      • selector (string): CSS selector for element mode
      • settle (number): For page mode, milliseconds to wait after each scroll for content to settle (default: 500). Raise for slow dynamic sites, lower for static sites.
      • share (boolean, default: false): Save to disk and return only the file path instead of the inline image
    • Returns: Inline base64 image when share is false, or { path, width, height, mimeType, ... } when share is true. Browser metadata { innerHeight, scrollHeight, pages } is included for non-screen modes.

11. scroll

    • Scroll by direction or to a viewport-page index
    • Type: observe tool
    • Optional inputs:
      • direction (string: up or down)
      • page (number): Viewport-page index to scroll to
      • pixels (number): Pixels to scroll, paired with direction

12. search

    • Search using the browser's default engine
    • Type: act tool
    • Required inputs:
      • text (string): Search query

13. select

    • Choose an option in a <select> element
    • Type: act tool
    • Required inputs:
      • selector (string): CSS selector for the <select>
    • Optional inputs (one is required):
      • text (string): Option visible text
      • value (string): Option value attribute

14. status

    • Return current Safari tabs and full tool surface
    • Type: observe tool
    • Returns: { tabs, tools }

15. type

    • Type text into an input field
    • Type: act tool
    • Required inputs:
      • text (string): Text to type
    • Optional inputs:
      • append (boolean, default: false): Append instead of replace
      • selector (string): CSS selector for the input
      • submit (boolean, default: false): Press Enter after typing

16. wait

    • Wait for selector or page text condition
    • Type: observe tool
    • Optional inputs (exactly one of the first three required):
      • selector (string): CSS selector to wait for
      • selectorGone (string): CSS selector to wait absent
      • text (string): Page text to wait for
      • timeoutMs (number): Timeout in milliseconds
    • Returns: { matched, elapsedMs }

17. window

    • Manage browser window tabs
    • Type: observe tool
    • Required inputs:
      • action (string: close, list, open, switch)
    • Optional inputs:
      • index (number): Tab index for close and switch
      • url (string): URL for open