What is iOS Simulator MCP Server

The iOS Simulator MCP Server is a Model Context Protocol (MCP) server designed to enable interactions with iOS simulators. It provides tools for obtaining information about the simulators, controlling user interface interactions, and inspecting UI elements, allowing for automated testing and quality assurance.

Use cases

This MCP server is particularly useful for AI-driven quality assurance tasks after implementing new features in applications. It allows AI assistants to validate and document user interface interactions, ensuring consistency and functionality through various automated commands.

How to use

Users can integrate the iOS Simulator MCP server with MCP clients like Cursor and Claude Code. After configuring the client to include the MCP server, users can employ it by issuing commands to interact with the simulator, such as verifying UI elements, entering text, or taking screenshots. This setup allows for automated testing workflows leveraging AI capabilities.

Key features

Key features of the iOS Simulator MCP Server include accessing the current simulator ID, interacting with the simulator UI by describing accessibility elements, inputting text, performing screen taps, swiping between coordinates, getting UI element information, capturing screenshots, and filtering tools using environment variables.

Where to use

This MCP server can be used in environments where automated testing and user interface interaction validation are required, particularly in macOS development setups with Xcode. It is suitable for QA teams and developers who are integrating automated testing with AI-assisted agents to enhance their testing process and improve software quality.

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.

Security Notice: Command injection vulnerabilities present in versions < 1.3.3 have been fixed. Please update to v1.3.3 or later. See SECURITY.md for details.

https://github.com/user-attachments/assets/453ebe7b-cc93-4ac2-b08d-0f8ac8339ad3

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 the prompts below 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)

Installation

This section provides instructions for integrating the iOS Simulator MCP server with different Model Context Protocol (MCP) clients.

Installation with Cursor

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

Option 1: Using NPX (Recommended)

1. Edit your Cursor MCP configuration file. You can often open it directly from Cursor or use a command like:

   # Open with your default editor (or use 'code', 'vim', etc.)
   open ~/.cursor/mcp.json
   # Or use Cursor's command if available
   # cursor ~/.cursor/mcp.json
   

2. Add or update the mcpServers section with the iOS simulator server configuration:
   Ensure the JSON structure is valid, especially if mcpServers already exists.
3. Restart Cursor for the changes to take effect.

Option 2: Local Development

1. Clone this repository:

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

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Edit your Cursor MCP configuration file (as shown in Option 1).
5. Add or update the mcpServers section, pointing to your local build:
   Important: Replace /full/path/to/your/ with the absolute path to where you cloned the ios-simulator-mcp repository.
6. 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. For more details on Claude Code MCP configuration, refer to the official documentation.

Option 1: Using NPX (Recommended)

1. Add the server using the claude mcp add command:

   claude mcp add ios-simulator npx ios-simulator-mcp
   

2. Restart any running Claude Code sessions if necessary.

Option 2: Local Development

1. Clone this repository, install dependencies, and build the project as described in the Cursor “Local Development” steps 1-3.
2. 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 ios-simulator-mcp repository.
3. Restart any running Claude Code sessions if necessary.

License

MIT