Shotter

MCP (Model Context Protocol) server for iOS Simulator automation. Provides tools for AI assistants to navigate iOS apps, interact with UI elements, and capture screenshots.

Features

• MCP Integration: Works with Claude Desktop, Claude Code, and other MCP-compatible clients

• Device Management: List, select, and boot iOS Simulator devices

• UI Automation: Tap, swipe, type, and navigate iOS apps

• Screenshot Capture: Visual analysis and high-quality screenshot saving

• Workflow Support: Load and execute YAML-defined navigation workflows

Installation

npm install
npm run build

Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "shotter": {
      "command": "node",
      "args": ["/path/to/shotter/dist/server.js"]
    }
  }
}

Claude Code

Add to your project's .mcp.json or global settings:

{
  "mcpServers": {
    "shotter": {
      "command": "node",
      "args": ["/path/to/shotter/dist/server.js"]
    }
  }
}

Available Tools

Device Management

UI Interaction

Workflow

Available Prompts

Usage Examples

Once configured, ask your AI assistant to:

"Select iPhone 16 Pro and launch the Settings app"

"Take a screenshot of the current screen"

"Tap on the Wi-Fi option in Settings"

"Navigate to Privacy settings and take a screenshot"

Workflow Format

Workflows define multi-step navigation sequences:

name: "My App Screenshots"
description: "Capture key screens from my app"

bundleId: "com.example.myapp"

devices:
  - "iPhone 16 Pro"
  - "iPad Pro"

maxIterations: 20
outputDir: "./screenshots"

steps:
  - goal: "Navigate to settings"
    hints:
      - "Look for a gear icon or Settings tab"
    screenshot: "settings.png"

  - goal: "Open the profile screen"
    screenshot: "profile.png"

YAML Fields

Step Fields

Requirements

• macOS with Xcode installed

• iOS Simulator

• Node.js 18+

• Facebook IDB (brew install idb-companion)

Development

npm run dev    # Watch mode
npm run build  # Compile TypeScript

How It Works

Shotter acts as an MCP server that:

1. Manages iOS Simulator device lifecycle (boot, select)

2. Proxies UI commands to ios-simulator-mcp for screen interaction

3. Provides navigation prompts optimized for AI assistants

4. Supports workflow files for repeatable multi-step automation

The AI assistant uses ui_view to see the screen, makes decisions about what to tap or type, and verifies actions succeeded before continuing.

License

ISC