# 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
```bash
npm install
npm run build
```
## Configuration
### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"shotter": {
"command": "node",
"args": ["/path/to/shotter/dist/server.js"]
}
}
}
```
### Claude Code
Add to your project's `.mcp.json` or global settings:
```json
{
"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:
```yaml
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](https://fbidb.io/) (`brew install idb-companion`)
## Development
```bash
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
