Installation Guide

This guide provides detailed instructions for setting up the iOS Simulator MCP server and integrating it with supported MCP clients.

Prerequisites

Before you begin, ensure your development environment meets the following requirements:

Operating System: macOS is required, as iOS simulators are only available on this platform.
Node.js: A recent version of Node.js must be installed.
Xcode: Xcode and its Command Line Tools must be installed. This includes the iOS simulators.
Facebook IDB: The idb command-line tool is required for most UI interactions. See the next section for detailed installation instructions.

Installing Facebook IDB

The official installation guide for IDB can sometimes be out of date. Below are tested methods for installing idb on a modern macOS system.

Method 1: Using Homebrew + pip (Recommended)

Install Homebrew: If you don't have Homebrew, install it with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Python:
```
brew install python
```
Install IDB using pip:
```
pip3 install --user fb-idb
```
Update your PATH: Ensure the directory where pip installs user binaries is in your system's PATH. This is typically ~/.local/bin.
```
export PATH="$HOME/.local/bin:$PATH"
```
To make this change permanent, add the line above to your shell configuration file (e.g., ~/.zshrc or ~/.bash_profile).
Verify the Installation:
```
idb --version
```

Method 2: Using asdf (Python Version Manager)

If you use asdf to manage your tool versions, follow these steps:

Install asdf:
```
brew install asdf
```

Add the Python plugin and install a version:

asdf plugin add python
asdf install python latest
asdf global python latest

Install IDB using pip:
```
pip install --user fb-idb
```
Update your PATH: As with the Homebrew method, ensure ~/.local/bin is in your PATH.
```
export PATH="$HOME/.local/bin:$PATH"
```
Add this to your ~/.zshrc or ~/.bash_profile.
Verify the Installation:
```
idb --version
```

MCP Client Setup

Cursor

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

Option 1: Using NPX (Recommended)

This method automatically fetches and runs the latest version of the server from npm.

Open your Cursor MCP configuration file (~/.cursor/mcp.json).

Add the following entry to the mcpServers object:

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

Restart Cursor for the changes to take effect.

Option 2: Local Development

Use this method if you are contributing to the server or want to run a local version.

Clone the repository:

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

Install dependencies and build the project:
```
npm install
npm run build
```

Edit ~/.cursor/mcp.json and point it to your local build. Remember to replace /full/path/to/your/ with the absolute path to the cloned repository.

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

Restart Cursor.

Claude Code

Claude Code's CLI can manage MCP servers directly.

Option 1: Using NPX (Recommended)

Add the server using the claude mcp add command:

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

Option 2: Local Development

Clone, install, and build the project as described in the Cursor local development steps.
Add the server, pointing to your local build. Remember to replace /full/path/to/your/ with the absolute path.
```
claude mcp add ios-simulator --command node --args "/full/path/to/your/ios-simulator-mcp/build/index.js"
```