Safari Web Inspector Bridge

Safari Web Inspector Bridge is an MCP server that gives AI agents the same capabilities a developer gets from Safari Web Inspector — inspect, observe, and automate WKWebViews running on connected iOS devices.

Architecture

graph TD
    Agent["AI Agent<br/>Claude, Codex, etc."]
    Bridge["MCP Server:<br /><code>safari-web-inspector-bridge</code>"]
    Proxy["managed child process: <code>ios-webkit-debug-proxy</code>"]
    Device["iOS Device<br/>WKWebView"]

    Agent <-->|"MCP <code>stdio</code>"| Bridge
    Bridge <-->|"WebSocket<br/>WebKit Inspector Protocol"| Proxy
    Proxy <-->|"usbmuxd<br/>(USB / Wi-Fi)"| Device

    style Agent fill:#f0f0f0
    style Bridge fill:#f0f0f0
    style Proxy fill:#f0f0f0
    style Device fill:#f0f0f0

The server spawns ios-webkit-debug-proxy as a child process, connects to the WebKit Inspector Protocol over WebSocket, and exposes everything as MCP tools. The proxy is managed for its full lifecycle -- started on init, health-checked, auto-restarted on crash, and killed on shutdown.

Proxy Lifecycle

stateDiagram-v2
    [*] --> Checking: Server starts
    Checking --> Spawning: Binary found
    Checking --> Error: Binary missing
    Spawning --> HealthCheck: Process started
    HealthCheck --> Ready: localhost:9221 responds
    HealthCheck --> Error: Timeout (10s)
    Ready --> Crashed: Process exits
    Crashed --> Spawning: Restart (once)
    Crashed --> Error: Already retried
    Ready --> Stopped: Graceful shutdown
    Stopped --> [*]

13 MCP Tools

Discovery: list_devices | list_inspectable_pages | connect

Observation: get_url | get_dom | get_network_log | get_console_log | screenshot

Automation: navigate | execute_javascript | click_element | type_text | wait_for

Prerequisites

macOS required for usbmuxd and iOS device connectivity
ios-webkit-debug-proxy: brew install ios-webkit-debug-proxy
iOS: Settings &rsaquo; Safari &rsaquo; Advanced &rsaquo; Web Inspector: enabled
target app WKWebView must have isInspectable = true

Installation

git clone https://github.com/andesco/safari-web-inspector-bridge.git
cd safari-web-inspector-bridge
npm install
npm run build

Add to Claude Code

claude mcp add safari-web-inspector-bridge node /path/to/safari-web-inspector-bridge/dist/index.js

Add to any MCP client

Add to your MCP configuration file:

{
  "mcpServers": {
    "safari-web-inspector-bridge": {
      "command": "node",
      "args": ["/path/to/safari-web-inspector-bridge/dist/index.js"],
      "env": {
        "SWIB_NETWORK_CAPTURE": "true",
        "SWIB_CONSOLE_CAPTURE": "true"
      }
    }
  }
}

Tools

Device & Connection

| Tool | Parameters | Returns | |------|-----------|---------| | list_devices | _(none)_ | [{ udid, name, os_version }] | | list_inspectable_pages | device_udid? string -- filter to one device | [{ page_id, title, url, app_bundle_id, device_udid }] | | connect | page_id string -- from list_inspectable_pages | { connected, page_id, url, title, warnings? } |

Observation

| Tool | Parameters | Returns | |------|-----------|---------| | get_url | _(none)_ | { url } | | get_dom | selector? string -- CSS selector (default: document.documentElement); outer_html? boolean (default: true) -- outerHTML vs textContent | { html } or { text } | | get_network_log | clear? boolean (default: false); filter_url? string -- regex; filter_status? string -- e.g. "302", "4xx" | [{ request_id, method, url, status, mime_type, response_headers, request_headers, redirected_from, redirected_to, timing, error }] | | get_console_log | clear? boolean (default: false); level? "log" \| "warn" \| "error" \| "info" | [{ level, text, timestamp, source_url, line_number }] | | screenshot | _(none)_ | MCP image content (base64 PNG) |

Automation

| Tool | Parameters | Returns | |------|-----------|---------| | navigate | url string | { url, title, status } | | execute_javascript | expression string; await_promise? boolean (default: true) | { result } -- JSON-serialized return value | | click_element | selector string -- CSS selector; index? number (default: 0) -- which match to click | { clicked, selector, tag_name } | | type_text | text string; selector? string -- focus this element first | { typed: true } | | wait_for | One of: selector? string, url_contains? string, network_idle? number (ms); plus timeout_ms? number (default: 10000) | { matched: true, elapsed_ms } |

Configuration

| Env Var | Default | Description | |---------|---------|-------------| | SWIB_AUTO_CONNECT | false | Auto-connect to the first inspectable page on startup | | SWIB_NETWORK_CAPTURE | true | Capture network requests on connect | | SWIB_CONSOLE_CAPTURE | true | Capture console messages on connect | | SWIB_PROXY_PORT | 9222 | Starting port for ios-webkit-debug-proxy device ports |

[!note] SWIB_NETWORK_CAPTURE and SWIB_CONSOLE_CAPTURE default to true — set to false to disable. SWIB_AUTO_CONNECT defaults to false — set to true to enable.

Example Workflow

sequenceDiagram
    participant Agent as AI Agent
    participant Bridge as MCP Server
    participant Proxy as ios-webkit-debug-proxy
    participant Device as iOS WKWebView

    Agent->>Bridge: list_inspectable_pages()
    Bridge->>Proxy: GET /json (devices + pages)
    Proxy-->>Bridge: page_id: "1", title: "Banks"
    Bridge-->>Agent: [{ page_id, title, url, app_bundle_id }]

    Agent->>Bridge: connect({ page_id: "1" })
    Bridge->>Proxy: WebSocket connect
    Proxy->>Device: WebKit Inspector attach
    Device-->>Proxy: Connected
    Bridge-->>Agent: { connected: true }

    Agent->>Bridge: get_network_log({ filter_url: "scotiabank" })
    Bridge-->>Agent: [{ url, status: 302, redirected_to: "scotiabank://..." }]

    Agent->>Bridge: execute_javascript("document.title")
    Bridge->>Device: Runtime.evaluate
    Device-->>Bridge: "Banks"
    Bridge-->>Agent: { result: "Banks" }

    Agent->>Bridge: click_element({ selector: "button.next" })
    Bridge->>Device: Runtime.evaluate (querySelector + click)
    Device-->>Bridge: clicked
    Bridge-->>Agent: { clicked: true, tag_name: "button" }

    Agent->>Bridge: wait_for({ url_contains: "/dashboard" })
    loop Poll until match
        Bridge->>Device: Runtime.evaluate (location.href)
        Device-->>Bridge: current URL
    end
    Bridge-->>Agent: { matched: true, elapsed_ms: 1230 }

    Agent->>Bridge: screenshot()
    Bridge->>Device: Page.snapshotRect
    Device-->>Bridge: base64 PNG
    Bridge-->>Agent: image content

Development

npm run build        # Compile TypeScript to dist/
npm run dev          # Watch mode (tsc --watch)
npm test             # Run tests (vitest)
npm run test:watch   # Watch mode tests
npm start            # Run the MCP server (node dist/index.js)

Project structure

src/
  index.ts               # Entry point, server setup, lifecycle
  types.ts               # Interfaces and config loader
  proxy-manager.ts       # Spawns and manages ios-webkit-debug-proxy
  device-discovery.ts    # Queries proxy for devices and pages
  webkit-connection.ts   # WebSocket connection to WebKit Inspector Protocol
  network-buffer.ts      # Ring buffer for network request entries (1000 max)
  tools/
    device-tools.ts      # list_devices, list_inspectable_pages, connect
    observation-tools.ts # get_url, get_dom, get_network_log, get_console_log, screenshot
    automation-tools.ts  # navigate, execute_javascript, click_element, type_text, wait_for

Safari Web Inspector Bridge