Troubleshooting Guide

If you encounter errors or issues using this MCP server, try the following troubleshooting steps before reporting a bug.

1. Check Prerequisites

  • macOS Only: This server only works on macOS with Xcode and iOS simulators installed.
  • IDB Tool: Ensure Facebook IDB is installed and available in your PATH. You can verify this by running idb --version in your terminal.
  • Node.js: Make sure Node.js is installed and up to date.

2. Installing IDB

The installation section in the official IDB documentation can be out of date. Since Python environments are notoriously complex, here are some reliable ways to install it.

Using Homebrew + pip

  1. Install Homebrew if you don't have it: 

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

  2. Install Python (if not already installed): 

    brew install python

  3. Install idb using pip: 

    pip3 install --user fb-idb

  4. Ensure your user base binary directory is in your PATH (often ~/.local/bin): 

    export PATH="$HOME/.local/bin:$PATH"
    Add the above line to your ~/.zshrc or ~/.bash_profile for persistence.

  5. Verify installation: 

    idb --version

Using asdf (Python version manager)

  1. Install asdf: 

    brew install asdf

  2. Add the Python plugin and install Python: 

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

  3. Install idb using pip: 

    pip install --user fb-idb

  4. Ensure your user base binary directory is in your PATH and reload your shell.

3. Common Issues & Fixes

"No booted simulator found"

  • Solution: Open Xcode and boot an iOS simulator manually from the "Window > Devices and Simulators" menu.
  • Verification: Run xcrun simctl list devices in your terminal to verify a simulator is listed with the state "(Booted)".

"idb: command not found" or other IDB errors

  • Solution: Your PATH environment variable is likely misconfigured. Follow the idb installation steps above carefully, especially the part about adding ~/.local/bin to your PATH.
  • Verification: Open a new terminal window and run idb --version.

Permission or File Errors

  • Cause: This often happens when using tools like screenshot or record_video.
  • Solution: Ensure you have write permissions for the specified output path. If you are using a relative path, check the IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR environment variable. If it's not set, the default is ~/Downloads.

Simulator UI Not Responding or Incorrect Coordinates

  • Cause: Simulators can sometimes get into a bad state. Also, be aware that the simulator's screen resolution (in pixels) is often a multiple (e.g., 3x) of its logical resolution (in points). Tools like ui_tap operate on points.
  • Solution:
    1. Restart the simulator and try again.
    2. Quit and relaunch Xcode if needed.
    3. Ask your AI agent to first use ui_describe_all to get the screen dimensions (frame) and then adjust tap/swipe coordinates accordingly.

4. Still Stuck?

  • Review the Installation Guide for setup instructions.
  • If the problem persists, please open an issue on GitHub and include the error message, your OS version, Xcode version, and the steps to reproduce the problem.