mcp idb

Local 2025-08-31 23:10:49 0
Developer Tools @noahlozevski/mcp-idb

Integration between Model Context Protocol (MCP) and Facebook's iOS Development Bridge (idb), enabling automated iOS device management and test execution through natural language.


MCP server integration for Facebook's iOS Development Bridge (idb).

Overview

This package provides integration between MCP (Model Context Protocol) and Facebook's idb (iOS Development Bridge), enabling automated iOS device management and test execution through MCP.

Start the server:

npx -y @noahlozevski/mcp-idb

Prerequisites

Installing idb

To install idb:

brew tap facebook/fb
brew install idb-companion

# verify installation
idb

For more details, visit the official idb GitHub repository.

Configuration

mcp-config.json Setup

To use idb in your MCP configuration, add the following to your mcp-config.json:

{
  "mcpServers": {
    "idb": {
      "command": "npx",
      "args": ["-y", "@noahlozevski/idb"]
    }
  }
}

Example use cases include:

  • Automated test development
  • Screenshot testing
  • Automated interactions ("tap the home button on the screen")
  • Installing / removing applications

Development

Code Formatting

This project uses Prettier for code formatting. To format your code:

npm run format        # Format all files

The formatting configuration can be found in .prettierrc at the root of the project.

Troubleshooting

Common issues and solutions:

  1. idb companion not found: Ensure idb-companion is installed via Homebrew
  2. Device not detected: Make sure the iOS device is:
  3. Connected via USB
  4. Trusted on the computer
  5. Has developer mode enabled

Contributing

Please follow the standard MCP contribution guidelines when making changes to this package.

License

This project is part of Mobile Control Plane (MCP) and follows Amazon's internal licensing policies.

[
  {
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "command": {
          "description": "The IDB command to execute (e.g., list-apps, screenshot, etc.).n- For a full list of commands, run 'idb help'.n- For help with a specific command, run 'idb <command> --help'.nnTo interact with the device (simulator):nIMPORTANT: Always try using the 'idb ui describe-all' command to identify buttons before dispatching UI actions.nIf that doesn't work, try using the following commands:n  n- **Tap**  n  - **Command:** 'idb ui tap X Y [--duration DURATION]'n  - **Description:** Simulates a tap at the given screen coordinates. Optionally, you can set the tap's duration.n  n- **Swipe**  n  - **Command:** 'idb ui swipe X_START Y_START X_END Y_END [--delta STEP_SIZE]'n  - **Description:** Simulates a swipe gesture from the start point to the end point. By default, the swipe moves in steps of 10 points; use '--delta' to change the step size.n  n- **Press a Button**  n  - **Command:** 'idb ui button {APPLE_PAY, HOME, LOCK, SIDE_BUTTON, SIRI} [--duration DURATION]'n  - **Description:** Simulates pressing a specified hardware button. The press duration can be adjusted with the '--duration' flag.n  n- **Inputting Text**  n  - **Command:** 'idb ui text "some text"'n  - **Description:** Types the provided text string into the target device.n  n- **Key Events**  n  - **Single Key:** 'idb ui key KEYCODE [--duration DURATION]'n  - **Key Sequence:** 'idb ui key-sequence KEYCODE1 KEYCODE2 ...'n  - **Description:** Simulates key press events. Use the single key command for one key press (with an optional duration) or the key sequence command for multiple sequential key events.nn**Frame and Coordinates in idb ui describe-all:**nThe output from 'idb ui describe-all' provides detailed layout information for each UI element. Each element includes a 'frame' object with:n- **x and y:** The coordinates of the element's top-left corner relative to the device screen.n- **width and height:** The dimensions of the element.nAdditionally, an 'AXFrame' string presents this data in a human-readable format like '{{x, y}, {width, height}}'.nThese values allow you to determine an element's position—commonly by calculating its center (x + width/2, y + height/2) for precise interactions. For instance, in the sample output, the "More, tab, 4 of 4" button has a frame starting at x=330, y=876.33 with a width of 110 and height of 45.67. A tap command such as 'idb ui tap 375 880' (which targets near the element's center) successfully triggers the button.n",
          "type": "string"
        },
        "options": {
          "description": "Optional arguments for the IDB command",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "command"
      ],
      "type": "object"
    },
    "name": "idb"
  }
]