iOS Simulator MCP Server for Windsurf: Setup & Config

What you can do with iOS Simulator in Windsurf

Choose it for assistant-led simulator QA using accessibility data, gestures, and visual captures.

• Exercise tap, typing, and swipe flows in an app.
• Install and launch a simulator build and test deep links.

Before you start: iOS Simulator in Windsurf

• Node.js
• macOS
• Xcode and installed iOS simulators
• Facebook IDB

Use release 1.3.3 or later according to the README security notice. The default capture directory is ~/Downloads when no output directory is configured.

iOS Simulator Windsurf configuration

1. Choose Windsurf configuration scope

   For iOS Simulator MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add iOS Simulator MCP Server to Windsurf

   Use the ios-simulator-mcp entry below in mcpServers. Keep iOS Simulator MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check iOS Simulator MCP Server in Windsurf

   iOS Simulator MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "ios-simulator-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ios-simulator-mcp"
      ],
      "env": {
        "IDB_UDID": "<optional target simulator UUID>",
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "<optional comma-separated tool names to exclude>",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "<optional directory for screenshots and recordings>"
      }
    }
  }
}

iOS Simulator tools available to Windsurf

iOS Simulator's stored tool list documents 17 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get_booted_sim_id

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for get_booted_sim_id.

Identify the simulator that is currently running.

open_simulator

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for open_simulator.

Start the Simulator application.

ui_describe_all

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_describe_all.

ui_tap

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_tap.

ui_type

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_type.

ui_swipe

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_swipe.

ui_describe_point

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_describe_point.

Inspect the accessibility element at a screen position.

ui_find_element

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_find_element.

Find accessibility elements matching labels, identifiers, or type filters.

ui_view

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for ui_view.

Return a compressed image of the current simulator display.

screenshot

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for screenshot.

record_video

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for record_video.

stop_recording

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for stop_recording.

install_app

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for install_app.

launch_app

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for launch_app.

Start an installed app using its bundle identifier.

terminate_app

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for terminate_app.

Stop a running app identified by its bundle ID.

open_url

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for open_url.

Open a URL in the simulator for navigation or link testing.

list_apps

After refreshing iOS Simulator in Windsurf settings, check Cascade's tool list for list_apps.

Enumerate installed apps with their names and bundle IDs.

iOS Simulator: full stored tool descriptions

Troubleshooting iOS Simulator in Windsurf

• Check npx ios-simulator-mcp (Node.js/npm) on the machine running Windsurf's MCP integration for iOS Simulator MCP Server; refresh MCP and inspect Cascade's tools.
• Check IDB_UDID, IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR, IOS_SIMULATOR_MCP_FILTERED_TOOLS for iOS Simulator MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• iOS Simulator MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires macOS, Xcode simulators, and IDB.
• Known limitation: The typing tool accepts printable ASCII only.
• Known limitation: Versions before 1.3.3 have a documented command injection issue.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions