Shotter

Provides MCP-based automation for iOS simulators, enabling device management, UI actions, and workflow-driven navigation.

typescript

0

GitHub Stars

typescript

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

Shotter is an MCP server that automates iOS Simulator tasks for AI assistants. It lets you manage simulators, interact with apps, capture screenshots, and run YAML-defined navigation workflows to streamline testing and UI exploration.

How to use

You use Shotter with an MCP client to control iOS Simulators from your AI assistant. Start by ensuring a target simulator is available, then boot or select a device, launch apps by bundle ID, and perform UI actions such as taps, swipes, and text entry. You can capture screenshots to verify results and load workflow YAML files for repeatable multi-step automation. Your assistant can request device lists, switch devices, interact with UI elements, take screenshots, and execute predefined workflows until you reach your goals.

How to install

Prerequisites: macOS with Xcode installed, iOS Simulator, Node.js 18+.

Step-by-step setup and run flow you should follow locally:

# Install dependencies and build the server
npm install
npm run build

# Optional: start in development/watch mode
npm run dev

Configuration and usage notes

Configure your MCP clients to connect to the Shotter server. For Claude Desktop, point the MCP server config to Shotter so your assistant can access device management, UI actions, and workflows.

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

Workflow and prompts

Load and execute YAML-defined navigation workflows to automate multi-step tasks across devices. You can list available workflows, load a workflow file, and let your AI assistant drive the steps with goal-oriented prompts.

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"

Security and troubleshooting

Keep your environment secure by limiting who can run the MCP server and access connected simulators. If you encounter issues, verify that the server process is running, the MCP client is connected to the correct URL/port, and that the target simulator is booted and active before attempting UI actions.

Requirements

macOS with Xcode installed
iOS Simulator
Node.js 18+
Facebook IDB (idb-companion) may be required for certain tooling on macOS.

Development

To work on Shotter locally, install dependencies and build in watch or compile mode as you develop.

npm run dev    # Watch mode
npm run build  # Compile JavaScript/TypeScript assets

Available tools

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_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 the focused field

screenshot

Save high-quality screenshot to a file

load_workflow

Load and parse a workflow YAML file

list_workflows

List available workflow files in a directory