ios-simulator-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the iOS Simulator MCP (Model Context Protocol) server - a tool that enables AI assistants to interact with iOS simulators through MCP. The project follows an intentionally simple single-file architecture where all logic is contained in src/index.ts.

Build and Development Commands

npm is the default; pnpm is also supported (a pnpm-lock.yaml, derived from package-lock.json via pnpm import, is committed). Substitute pnpm for npm in any command below.

# Install dependencies
npm install

# Build the TypeScript project (compiles to build/)
npm run build

# Development with automatic rebuild on changes
npm run watch

# Run the MCP inspector for testing
npm run dev

# Start the compiled server
npm start

Architecture

The entire server implementation is in src/index.ts (single file by design). The server:

• Uses the MCP SDK to expose tools for iOS simulator interaction
• Wraps xcrun simctl and Facebook's idb commands
• Validates all inputs with Zod schemas
• Implements security best practices with -- argument separation
• Supports environment-based tool filtering via IOS_SIMULATOR_MCP_FILTERED_TOOLS
• Handles output paths with IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR environment variable

Available MCP Tools

The server provides these tools (can be filtered via environment variables):

• get_booted_sim_id - Get the currently booted simulator ID
• open_simulator - Open the iOS Simulator application
• ui_describe_all - Get accessibility info for the entire screen
• ui_tap - Tap at coordinates
• ui_type - Input text
• ui_swipe - Swipe gesture
• ui_describe_point - Get element at specific coordinates
• ui_find_element - Search accessibility tree for elements by label, identifier, or type
• ui_view - Get compressed screenshot as base64 JPEG
• screenshot - Save screenshot to file
• record_video - Start video recording
• stop_recording - Stop video recording
• install_app - Install an app bundle (.app or .ipa) on the simulator
• launch_app - Launch an app by bundle identifier
• terminate_app - Terminate a running app by bundle identifier
• open_url - Open a URL or deep link in the simulator
• list_apps - List all installed apps with their bundle IDs and display names