📌Overview

Purpose: To provide a Model Context Protocol (MCP) server for effective interaction with iOS simulators, enabling information retrieval, UI control, and inspection of UI elements.

Overview: The iOS Simulator MCP Server facilitates interaction with iOS simulators by offering tools to gather simulator data, manipulate the user interface, and inspect components to enhance quality assurance processes in software testing.

Key Features:

Simulator Interaction: Retrieve the ID of the currently booted iOS simulator and manipulate its UI, ensuring seamless testing and validation.
UI Control: Execute actions such as tapping, text input, swiping, and gathering information about UI elements, making it easier to automate UI tests.
Visual Documentation: Capture screenshots and record videos of simulator sessions, aiding in comprehensive documentation and review of the testing process.

iOS Simulator MCP Server

A Model Context Protocol (MCP) server for interacting with iOS simulators. This server allows you to interact with iOS simulators by getting information about them, controlling UI interactions, and inspecting UI elements.

Features

Get the ID of the currently booted iOS simulator
Interact with the simulator UI:
- Describe all accessibility elements on screen
- Tap on screen coordinates
- Input text
- Swipe between coordinates
- Get information about UI elements at specific coordinates
- Take screenshots of the simulator screen
Filter specific tools using environment variables

Configuration

Environment Variables

IOS_SIMULATOR_MCP_FILTERED_TOOLS: A comma-separated list of tool names to filter out from being registered. For example: screenshot,record_video,stop_recording

Use Case: QA Step via MCP Tool Calls

This MCP server allows AI assistants integrated with a Model Context Protocol (MCP) client to perform Quality Assurance tasks by making tool calls. This is useful immediately after implementing features to help ensure UI consistency and correct behavior.

How to Use

After a feature implementation, instruct your AI assistant within its MCP client environment to use the available tools. For example, in Cursor's agent mode, you could use prompts to quickly validate and document UI interactions.

Example Prompts

Verify UI Elements:

Verify all accessibility elements on the current screen

Confirm Text Input:

Enter "QA Test" into the text input field and confirm the input is correct

Check Tap Response:

Tap on coordinates x=250, y=400 and verify the expected element is triggered

Validate Swipe Action:

Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior

Detailed Element Check:

Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality

Take Screenshot:

Take a screenshot of the current simulator screen and save it to my_screenshot.png

Record Video:

Start recording a video of the simulator screen (saves to ~/Downloads/simulator_recording_$DATE.mp4 by default)

Stop Recording:

Stop the current simulator screen recording

Prerequisites

Node.js
macOS (as iOS simulators are only available on macOS)
Xcode and iOS simulators installed
Facebook IDB tool (see install guide at https://fbidb.io/docs/installation)

Installation

Instructions for integrating the iOS Simulator MCP server with different MCP clients.

Installation with Cursor

Cursor manages MCP servers through its configuration file located at ~/.cursor/mcp.json.

Option 1: Using NPX (Recommended)

Edit your Cursor MCP configuration file:
```
open ~/.cursor/mcp.json
```

Add or update the mcpServers section with the iOS simulator server configuration:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"]
    }
  }
}

Restart Cursor for the changes to take effect.

Option 2: Local Development

Clone this repository:

git clone https://github.com/joshuayoes/ios-simulator-mcp
cd ios-simulator-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Edit your Cursor MCP configuration file.

Add or update the mcpServers section, pointing to your local build:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "node",
      "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
    }
  }
}

Important: Replace /full/path/to/your/ with the absolute path to where you cloned the repository.

Restart Cursor for the changes to take effect.

Installation with Claude Code

Claude Code CLI can manage MCP servers using the claude mcp commands or by editing its configuration files directly.

Option 1: Using NPX (Recommended)

Add the server using the claude mcp add command:

claude mcp add ios-simulator --command npx --args "-y,ios-simulator-mcp"

Restart any running Claude Code sessions if necessary.

Option 2: Local Development

Clone this repository, install dependencies, and build the project as described in the Cursor "Local Development" steps 1-3.
Add the server using the claude mcp add command, pointing to your local build:
```
claude mcp add ios-simulator --command node --args "/full/path/to/your/ios-simulator-mcp/build/index.js"
```
Important: Replace /full/path/to/your/ with the absolute path to where you cloned the repository.
Restart any running Claude Code sessions if necessary.

License

MIT