mcp-server-simulator-ios-idb: driving iOS simulators from an LLM over MCP

The gap this server fills between a model and a simulator

An LLM can write Swift and reason about UI, but it cannot see or touch a running simulator. Facebook's idb already exposes that surface programmatically: booting devices, installing apps, tapping coordinates, capturing screenshots. What idb does not do is accept a sentence. This project sits in that gap. It is a Model Context Protocol server, so an MCP-capable client such as Claude Desktop or Cline can call it as a tool, and it also exports a library entry point for embedding.

The audience is narrow and specific. You need macOS, because the package declares "os": ["darwin"] in its engines field and the README lists macOS as a requirement. You need Xcode with iOS simulators installed. You need Node.js v20.0.0 or higher and Homebrew, because the install script uses Homebrew to fetch idb-companion. If any of those is missing, the server is not the right starting point. This is a tool for an iOS developer who wants an assistant to reproduce a bug, walk a flow, or grab a screenshot without leaving the chat window.

How the parser, orchestrator and IDB manager chain together

The repository layout makes the data flow reasonably legible. src/parser holds the natural language parser, src/orchestrator holds the command orchestrator, src/idb holds the IDB manager, src/adapters holds adapter components, and src/mcp holds the MCP server itself. The advanced usage example in the README wires three of these together explicitly: an IDBManager, an NLParser, and an MCPOrchestrator constructed as new MCPOrchestrator(parser, idbManager). Two further exports, ParserToOrchestrator and OrchestratorToIDB, name the handoff points between stages.

So the path is: a natural language string arrives, the parser turns it into a structured instruction, the orchestrator dispatches it, and the IDB manager calls into idb. The README's basic example shows the orchestrator's public shape, orchestrator.processInstruction('tap at 100, 200'), which returns an object with a data field. That is a thin interface over a fairly deep stack, and the depth is where the friction lives: a phrasing the parser does not recognise fails before idb is ever invoked. The README describes the parser as supporting a table of commands, but the table is cut off mid-row in the published README, so the full accepted vocabulary is not documented in one place.

Installing it: Homebrew, a virtualenv and the postinstall script

The README presents two routes. The shortest is to ask Cline to add the server, which the README says handles dependency management and configuration automatically. The manual route is more transparent and is what you want if you intend to debug anything.

Clone the repository, create a Python virtual environment, then install and build:

git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
cd mcp-server-simulator-ios-idb
python3 -m venv venv
source venv/bin/activate
npm install
npm run build
npm start

npm install is not a passive step here. package.json defines a postinstall script that makes scripts/install_dependencies.sh executable and runs it, and the README states the install process checks for macOS, installs idb-companion via Homebrew, and installs fb-idb via pip inside the virtual environment. That ordering matters: the pip install targets the virtualenv, so the virtualenv should exist and be active before npm install runs. The README also warns that if you close the terminal you must reactivate with source venv/bin/activate before running npm start again.

Once the server is running, register it with an MCP client. The README gives this Claude Desktop configuration, pointing at the built entry point:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "node",
      "args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
      "env": {}
    }
  }
}

After that, the README's example prompts are the first real use: "create a simulator session with iPhone 14", then "install app /path/to/my-app.ipa", "launch app com.example.myapp", "tap at 100, 200", and "take a screenshot". The screenshot prompt is the cheapest way to confirm the whole chain works, because it exercises the parser, the orchestrator, the IDB manager and the simulator in one call and returns a path you can open.

Where this server is the wrong tool

The macOS constraint is not a packaging detail, it is the boundary of the project. package.json restricts engines to darwin, and the README lists macOS as a requirement. If your build fleet is Linux, this server cannot run there, and no amount of container work changes that, because iOS simulators themselves are a macOS facility.

The second limitation is the natural language layer. Everything the model sends passes through the parser first, and the parser recognises a finite set of phrasings. The README's command tables list alternatives such as "create session" and "create simulator iPhone 12", which tells you the parser accepts variants rather than one canonical string. But the published README truncates the table, and there is no grammar reference. In practice that means a model that paraphrases freely will occasionally produce a command the parser rejects, and the failure will look like the simulator ignoring the request rather than a syntax error. If you need deterministic, scriptable control, calling idb directly removes that layer entirely.

The third limitation is operational: the server depends on a Python virtualenv that must be reactivated. That is fine on a developer laptop and awkward in any scheduled or headless context, where a stale shell means npm start quietly fails to find fb-idb.

Against Appium and against calling idb yourself

Appium is the obvious alternative for iOS UI automation, and the difference is architectural rather than cosmetic. Appium is a WebDriver-protocol server: you write a test in a client library, the driver translates it into WebDriver commands, and the simulator is driven through XCUITest. The unit of work is a test case you author and version. This project's unit of work is a sentence a model generates at runtime. Appium gives you reproducibility, a large ecosystem and cross-platform reach; it gives you nothing to a model that wants to poke at a simulator mid-conversation.

Calling idb directly is the other alternative, and it is closer to this project than Appium is. You get the same underlying capability with none of the parser risk: idb_companion and the fb-idb Python client expose the operations, and you script them. What you lose is the MCP integration, which is the actual product here. An MCP client cannot call a shell script unless you wrap it, and wrapping it well is precisely the work this repository has already done, down to the adapters and the orchestrator's processInstruction interface. The trade is parser unpredictability in exchange for a tool the model can invoke natively.

Licence, maintenance and the cost of upgrading

The project is Apache-2.0, and the repository carries both a LICENSE file and a LICENSES/ directory alongside a REUSE.toml, which suggests REUSE-compliant licence metadata rather than a single bare licence file. Apache-2.0 permits commercial use, modification and redistribution provided you retain notices and state changes; it also includes an explicit patent grant. That is a permissive position, and it is the same licence the surrounding tooling tends to use. None of this is legal advice, and if you redistribute a modified build, the NOTICE and attribution obligations are worth reading in full rather than skimming.

The maintenance signal is mixed in an informative way. The last push to main was on 2026-09-10, five days before this writing, so the repository is not dormant. But the two published releases, 1.0.0 and 1.0.1, both date from 2025-04-02. Commits are landing without tagged releases, which means if you depend on a version number you are depending on something that has not moved in a long while. Upgrading is therefore a source-level exercise: pull main, run npm install again so the postinstall script re-checks idb-companion and fb-idb, then npm run build. The dependency surface is small (the MCP SDK, uuid and zod), so the realistic upgrade risk is not the Node packages but the external idb tooling that Homebrew and pip fetch.

Using it as a library instead of as an MCP server

The README documents two consumption modes, and the second one is easy to overlook. Beyond the MCP server, the package exports createMCPServer, which returns an orchestrator you can drive yourself. That matters if you want the natural language layer without an MCP client in the loop, for instance inside an existing Node tool that already has its own command handling.

The advanced example goes further and exposes IDBManager, NLParser and MCPOrchestrator as separate imports, plus the adapter types ParserToOrchestrator and OrchestratorToIDB. With IDBManager alone you can call typed methods such as createSimulatorSession({ deviceName: 'iPhone 12', platformVersion: '15.0' }) and tap(sessionId, 100, 200), skipping the parser entirely. That is the escape hatch for the parser limitation described earlier: if your phrasing is unpredictable but your commands are known, use IDBManager directly and keep the MCP transport. The README does not show a way to register a custom phrasing with the parser, so treating the parser as fixed and the manager as programmable is the safer assumption.

Editorial conclusion

Adopt it if you are already on macOS with Xcode simulators and you want an assistant to drive a simulator through idb rather than through a hand-rolled script; the Apache-2.0 licence and the library export make it reasonable to embed. Do not adopt it if your CI runs on Linux, or if you need a documented command reference, because the README's command tables are truncated and the parser's accepted phrasings are only partly listed. Before wiring it into anything, run npm run build and npm start once with the virtualenv active, confirm that scripts/install_dependencies.sh actually placed idb-companion and fb-idb on the machine, and check that the command you plan to send is one of the phrasings the parser recognises.

Frequently asked questions

Official sources

1. InditexTech/mcp-server-simulator-ios-idb on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases