repository·main·Indexed 24 days ago
https://github.com/joshuayoes/ios-simulator-mcpAn MCP server (v1.6.0) that enables AI assistants to interact with iOS simulators on macOS. It provides tools for automated UI testing, app installation, and visual inspection, including capabilities to tap, type, swipe, find UI elements via the accessibility tree, capture screenshots, and record videos. Requires Node.js, Xcode, and the Facebook IDB tool.
Most tools in this MCP server accept an optional udid parameter to specify which simulator to target. The UDID must follow the format: UUID (8-4-4-4-12 hexadecimal characters).
Alternatively, you can set the IDB_UDID environment variable to define a default target simulator for all tool calls.
If you use asdf to manage Python versions, follow these steps:
asdf tool and the python plugin.fb-idb using python -m pip install --user fb-idb.~/.local/bin) to your PATH.idb -h.# 1. Install asdf and python plugin
brew install asdf
asdf plugin add python
# 2. Install and set Python version
asdf install python latest
asdf global python latest
asdf set python <latest-version> -u
asdf reshim
# 3. Install idb
python -m pip install --user fb-idb
# 4. Add to PATH (add to ~/.zshrc or ~/.bash_profile for persistence)
export PATH="$HOME/.local/bin:$PATH"
# 5. Verify
idb -hBefore using the iOS Simulator MCP server, ensure your environment meets these requirements:
PATH.The iOS Simulator MCP Server allows AI assistants to interact with iOS simulators.
You can install the server directly in Cursor using the following configuration:
npx -y ios-simulator-mcpIntegrate the server with Claude Code CLI using the claude mcp command.
Run the following command to add the server:
claude mcp add ios-simulator npx ios-simulator-mcpclaude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"Note: Replace /full/path/to/your/ with the absolute path to your cloned repository. Restart any running Claude Code sessions after installation.
You can integrate the iOS Simulator MCP server with Cursor using either npx (recommended) or by pointing to a local development build.
~/.cursor/mcp.json.mcpServers section:{
"mcpServers": {
"ios-simulator": {
"command": "npx",
"args": ["-y", "ios-simulator-mcp"]
}
}
}git clone https://github.com/joshuayoes/ios-simulator-mcp
cd ios-simulator-mcp
npm install
npm run build~/.cursor/mcp.json and add the configuration pointing to your absolute build path:{
"mcpServers": {
"ios-simulator": {
"command": "node",
"args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
}
}
}/full/path/to/your/ with your actual absolute path and restart Cursor.To manually verify that the iOS Simulator MCP server tools are functioning correctly, you can execute a sequence of tool calls within an MCP client (such as Cursor). The following test case uses the native Photos app on iOS 17.2 as a benchmark.
Note: If you are using a different iOS version or a different app, you may need to adjust the search criteria or element types used in the sequence.
1. Open the native Photo app in the iOS simulator.
2. Call `get_booted_sim_id` to get the UDID of the booted simulator.
3. Call `record_video` to start recording a screen recording of the test.
4. Call `ui_describe_all` to make sure we are on the All Photos tab.
5. Call `ui_find_element` with `{ "search": ["Search"], "type": "Button" }` to find the Search tab button by its label.
6. Call `ui_describe_point` to verify the coordinates returned by `ui_find_element` for the Search tab button.
7. Call `ui_tap` to tap the Search tab button.
8. Call `ui_tap` to focus on the Search text input.
9. Call `ui_type` to type "Photos" into the Search text input.
10. Call `ui_describe_all` to describe the page and find the first photo result.
11. Call `ui_describe_point` to find the x and y coordinates for the first photo result touchable area.
12. Call `ui_tap` to tap the coordinates of the first photo result touchable area.
13. Call `ui_swipe` to swipe from the center of the screen down to dismiss the photo and go back to the All Photos tab.
14. Call `ui_describe_all` to describe the page and see we are the All Photos tab.
15. Call `screenshot` to take a screenshot of the current page.
16. Call `ui_view` to view the current page.
17. Call `stop_recording` to stop the screen recording.If you prefer using Homebrew, follow these steps to install Python and IDB:
fb-idb using pip3 with the --user flag.~/.local/bin) to your PATH to ensure the idb command is recognized.idb -h.The iOS Simulator MCP server supports the following environment variables for fine-grained control over its behavior. These can be passed via the env key in your MCP client configuration (e.g., mcp.json).
| Variable | Description | Example |
|---|---|---|
IOS_SIMULATOR_MCP_FILTERED_TOOLS | A comma-separated list of tool names to filter out from being registered. | screenshot,record_video,stop_recording |
IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR | Specifies a default directory for output files like screenshots and video recordings. Defaults to ~/Downloads. | ~/Code/awesome-project/tmp |
IOS_SIMULATOR_MCP_IDB_PATH | Specifies a custom path to the idb executable. Defaults to idb in your PATH. | ~/bin/idb |
{
"mcpServers": {
"ios-simulator": {
"command": "npx",
"args": ["-y", "ios-simulator-mcp"],
"env": {
"IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording",
"IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp",
"IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb"
}
}
}
}If you encounter permission or file-related errors (e.g., when saving screenshots or recordings):
~/Downloads, to rule out permission restrictions.If the MCP server reports that no booted simulator is found:
xcrun simctl list devices in your terminal to ensure a device is listed as Booted.If you encounter idb: command not found or general IDB errors:
idb binary is included in your system PATH. You can test this by running idb --version in your terminal.