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 › Safari › Advanced › 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

Observation

Automation

Configuration

[!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