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

Tool	Description
list_devices	List available iOS simulators with names, UDIDs, and states
select_device	Boot a simulator and set it as active (fuzzy name matching)
launch_app	Launch an app by bundle ID on the active device

UI Interaction

Tool	Description
ui_view	Capture screenshot for visual analysis
ui_describe_all	Get accessibility info with coordinates for all UI elements
ui_tap	Tap at specific coordinates
ui_swipe	Swipe gesture (for scrolling and navigation)
ui_type	Type text into focused field
screenshot	Save high-quality screenshot to a file

Workflow

Tool	Description
load_workflow	Load and parse a workflow YAML file
list_workflows	List available workflow files in a directory

Available Prompts

Prompt	Description
navigate	System prompt with iOS Simulator navigation strategies
workflow-step	Format a workflow step with goal and hints for execution

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

Field	Required	Description
name	Yes	Workflow name
description	No	Workflow description
bundleId	Yes	App bundle identifier
devices	Yes	List of simulator device names (fuzzy matched)
runBefore	No	Script to run before steps for each device
maxIterations	No	Max iterations per step (default: 20)
outputDir	No	Screenshot output directory (default: ./screenshots)
steps	Yes	List of navigation steps

Step Fields

Field	Required	Description
goal	Yes	What to accomplish
hints	No	Hints to help navigate
screenshot	No	Filename to save screenshot after step completes

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