lookin-mcp

# lookin-mcp-ios

MCP Server for iOS UI inspection — lets any AI agent (Claude Code, Cursor, Codex, etc.) inspect live iOS app UI hierarchy, attributes, and screenshots via LookinServer, no Lookin.app required.

---

## Prerequisites

- iOS App integrated with [LookinServerMCP](https://github.com/hepiao3/LookinServer), running on simulator or device
- Node.js 18+

### iOS Integration

Add the following to your `Podfile`:

```ruby
pod 'LookinServerMCP', :configurations => ['Debug']
```

> Only included in Debug builds — safe to leave in your Podfile permanently.

---

## How It Works

### Device Support

The MCP Server supports both iOS simulators and physical devices:

**iOS Simulator:**
```
AI Agent (Claude Code / Cursor / Codex / ...)
    ↓ stdio (MCP protocol)
lookin-mcp-ios (Node.js)
    ↓ HTTP local port
LookinServer (embedded in iOS App)
```

**Physical Device:**
```
AI Agent (Claude Code / Cursor / Codex / ...)
    ↓ stdio (MCP protocol)
lookin-mcp-ios (Node.js)
    ↓ native usbmuxd socket (/var/run/usbmuxd)
    ↓ TCP proxy on :47191
LookinServer (embedded in iOS App)
```

### Device Selection

- **Single device**: Automatically connects when the app starts
- **Multiple devices**: Prompts user to select device via `lookin_connect_device` tool
- **Device events**: Automatically reconnects when a physical device is unplugged (falls back to simulator)

---

## Installation

### Claude Code

```bash
Claude MCP add --scope user lookin -- npx -y lookin-mcp-ios
```

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "lookin": {
      "command": "npx",
      "args": ["-y", "lookin-mcp-ios"]
    }
  }
}
```

### Codex

Add to `~/.codex/config.yaml`:

```yaml
mcp_servers:
  - name: lookin
    command: npx
    args:
      - -y
      - lookin-mcp-ios
```

---

## Tools

### `lookin_list_devices`

Lists all connectable iOS targets: USB physical devices and booted simulators.

**Parameters:** None