# An MCP server that turns plain English into idb calls against a booted iOS simulator

> This server from InditexTech puts an iOS simulator behind natural language: a parser interprets an instruction, an orchestrator routes it, and an IDB manager performs taps, screenshots, app installs, and crash log collection against a real simulator session. What is worth knowing before you install is that npm install runs a shell script that installs Homebrew and pip packages for you, and that the package metadata declares macOS as a hard requirement.

**InditexTech/mcp-server-simulator-ios-idb** — A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.

- Repository: https://github.com/InditexTech/mcp-server-simulator-ios-idb
- Stars: 315 · Forks: 24
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/inditextech-mcp-server-simulator-ios-idb

## npm install runs a shell script that installs Homebrew and pip packages

The dependency install has side effects beyond downloading JavaScript. The package defines a `postinstall` script that makes `scripts/install_dependencies.sh` executable and runs it, and that script is documented as checking that you are on macOS, installing `idb-companion` via Homebrew, and installing `fb-idb` via pip inside the virtual environment.

Three things follow. First, an `npm install` on a machine that does not meet the requirements will attempt machine-level changes rather than failing cleanly at the dependency step. Second, the install needs a POSIX shell, since the script is invoked with a chmod and a direct path.

Third, the platform requirement is declared in the manifest rather than only in prose: the engines field requires Node 20 or newer and sets the operating system to `darwin`, so npm will refuse to install this package anywhere but macOS.

The runtime dependencies themselves are modest, three packages: the Model Context Protocol SDK, `uuid`, and `zod` for validation. Everything heavy comes from idb rather than from npm.

The recommended route skips all of it: ask Cline to add the server by URL and let it handle dependency management and configuration.

## The Python virtual environment is created by hand in a TypeScript project

The manual install creates a Python environment inside a Node project, which is odd until you notice what `fb-idb` is: a Python package. The sequence is clone, create the environment, activate it, install npm dependencies, build, and start.

```bash
# Clone the repository
git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
cd mcp-server-simulator-ios-idb

# Create and activate Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Unix/macOS

# Install dependencies
npm install

# Build the project
npm run build

# Start the project
npm start

# Run tests
npm test
```

The activation step has a documented consequence that will bite anyone returning to the terminal later: the environment has to stay active while the server runs, and if the terminal is closed you must run `source venv/bin/activate` again before `npm start`. A server that fails because a virtual environment went dormant is a confusing first experience, and the note exists because it happens.

The build step is not optional either, since `npm start` runs the compiled output rather than the TypeScript sources.

## An NLParser feeds an orchestrator that talks to an IDB manager

The source layout is the architecture. Under `src/` there are `adapters/`, `idb/` for the IDB manager implementation, `mcp/` for the MCP server implementation, `orchestrator/` for the command orchestrator, `parser/` for the natural language parser, and `index.ts` as the entry point, with TypeScript type definitions in `types/` and the installation scripts in `scripts/`.

There are two ways to use it, and the documentation is explicit that both are supported: direct MCP integration, or as a standalone library.

The library route exposes a single entry point for the common case, where `createMCPServer()` returns an orchestrator and you call `orchestrator.processInstruction('create session')` or `orchestrator.processInstruction('tap at 100, 200')`.

The advanced route exposes the individual components, `IDBManager`, `NLParser`, `MCPOrchestrator`, `ParserToOrchestrator`, and `OrchestratorToIDB`, wired together as `new MCPOrchestrator(parser, idbManager)`. You then call the manager directly, for example `idbManager.createSimulatorSession({ deviceName: 'iPhone 12', platformVersion: '15.0' })` followed by `idbManager.tap(sessionId, 100, 200)`.

That split tells you where the natural language handling ends: the parser only needs to be involved if you want instructions, and everything below it is an ordinary typed API.

## Two different things are called a session in the command list

The supported commands separate device inventory from agent sessions, and the naming is easy to trip over.

Device level commands cover the simulators themselves: list simulators to see what is available, list booted simulators to see what is running, boot simulator by UDID, shutdown simulator by UDID, and focus simulator to bring a window to the front. Note that booting and shutting down address a device by UDID, an identifier such as `5A321B8F-4D85-4267-9F79-2F5C91D142C2`, while creating a session takes a friendly name instead, as in create simulator iPhone 12.

Session level commands are separate: create session, terminate session, and list simulator sessions. So a session is the server's handle on a running simulator, and it is not the same thing as a booted device. `close simulator` is offered as a synonym for terminating a session, which is one more reminder that the two vocabularies overlap in everyday speech and not in the command table.

The library API reflects the same split, since `createSimulatorSession` returns an identifier that later calls such as `tap` take as their first argument.

If you are scripting this, the useful habit is to resolve a device name to a UDID with list simulators before booting, rather than assuming the friendly name is accepted everywhere.

## The client registration points at a file that only exists after a build

Connecting the server to Claude or another assistant is a JSON block added to the MCP settings, and the detail that matters is what it points at.

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

The `args` path is `dist/index.js`, the compiled output, not `src/index.ts`. Register the server before running the build and the client will start a path that does not exist, and the resulting error looks like a configuration problem rather than a missing build step. The `command` is plain `node`, and `env` is empty.

The server key is `ios-simulator`, which is the name your tools will be namespaced under.

Once it is connected, the interaction is natural language, and the examples given are short imperative lines: create a simulator session with iPhone 14, install app at a path to an ipa, launch app by bundle identifier, tap at a coordinate, or take a screenshot. Those five are a good smoke test, because between them they cover session creation, app installation, app launch, UI input, and evidence capture.

## The test suite needs an experimental VM flag to run

The npm scripts are short and one of them is unusual. Both `test` and `test:coverage` set `NODE_OPTIONS=--experimental-vm-modules` before invoking jest, which is what lets jest run ES modules under the module type declared in the manifest.

The package is `"type": "module"` with `main` set to `dist/index.js`, so the compiled output is ESM as well, and jest is configured through `ts-jest` with a `jest.config.js` at the root. The TypeScript source is compiled by a plain `tsc` invocation for the build, and the dev dependencies are the jest set: jest, ts-jest, the jest types, the Node types, and TypeScript 5.

If you run `npm test` after a fresh clone without the flag, the failure is about module resolution rather than about your code, which is the sort of thing that sends people looking in the wrong place.

The project also carries the usual governance and tooling files for a corporate repository: a `CHANGELOG.md`, a `SECURITY.md`, a `CODE_OF_CONDUCT.md`, a `CONTRIBUTING.md`, a REUSE configuration with a `LICENSES/` directory, a repolinter configuration, and a Sonar properties file.

## Both releases were tagged in April 2025 while commits continue

The release history is two tags, 1.0.0 and 1.0.1, and they were created five minutes apart on 2025-04-02. The manifest still declares 1.0.1.

Meanwhile the last push to the main branch is dated 2026-09-24, roughly eighteen months later. So the repository is receiving work while the published version has not moved past the day it was first stamped at 1.0.1.

Two consequences follow for anyone pinning. A `1.0.1` pin gives you the state of the tree on that April morning, not the state on the branch today, and the documentation you read on the default branch may describe behaviour that predates or postdates that tag.

The project is also listed on an MCP directory, `glama.json` configures that listing, and a `demo/` directory holds a demo recording. Those are the artefacts a visitor lands on first, and all of them can be newer than the release they describe.

Licensing is Apache 2.0 with a REUSE-compliant `LICENSES/` directory, which matters for a repository published under a corporate organisation and reused internally.

## Conclusion

The server fits an iOS developer who wants an assistant to drive a simulator for testing and debugging, since the capability list covers sessions, app lifecycle, UI interaction, accessibility elements, video recording, crash logs, and extras like keychain and contacts access. It does not fit a Linux or Windows CI runner, because the package declares macOS as its only supported platform and iOS simulators do not exist elsewhere. Before installing, expect the install step to touch Homebrew and pip, keep the Python virtual environment activated between sessions, and build before registering the server with your client, since the registered entry point is a compiled file.

## FAQ

### What exactly does an MCP server do?

It exposes tools to an LLM over a standard protocol so the model can act on a real system instead of only describing what it would do. In this server the model receives simulator control as natural language instructions, which a parser turns into idb operations against a booted iOS simulator.

### What are the requirements for the iOS simulator MCP server?

macOS, because iOS simulator support needs it, Node.js 20 or newer, Homebrew for dependencies, and Xcode with iOS simulators installed. The package manifest also declares the operating system as darwin, so npm will refuse to install it elsewhere.

### How do I install mcp-server-simulator-ios-idb?

The easiest route is to ask Cline to add the server by repository URL and let it handle dependency management and configuration. Manually you clone, create and activate a Python virtual environment, run npm install, npm run build, and then npm start, keeping the environment activated.

### What does npm install do beyond downloading packages?

It runs a postinstall script that makes scripts/install_dependencies.sh executable and executes it. That script checks for macOS, installs idb-companion through Homebrew, and installs fb-idb with pip inside the virtual environment.

### What can mcp-server-simulator-ios-idb control?

Simulator sessions including create, terminate, and list, plus boot, shutdown, and focus; app install, launch, terminate, permissions, and state checks; UI actions such as tap, swipe, and text input with accessibility elements and video recording; and debugging with screenshots, system logs, and crash logs. Advanced features add location simulation, media injection, URL schemes, contacts, and keychain access.

## Sources

- [InditexTech/mcp-server-simulator-ios-idb on GitHub](https://github.com/InditexTech/mcp-server-simulator-ios-idb)
- [Issues](https://github.com/InditexTech/mcp-server-simulator-ios-idb/issues)
- [License: Apache-2.0](https://github.com/InditexTech/mcp-server-simulator-ios-idb/blob/main/LICENSE)
- [README](https://github.com/InditexTech/mcp-server-simulator-ios-idb/blob/main/README.md)
- [Releases](https://github.com/InditexTech/mcp-server-simulator-ios-idb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/inditextech-mcp-server-simulator-ios-idb