Skip to content
Back to search

mcp-server-simulator-ios-idb

A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/InditexTech/mcp-server-simulator-ios-idb with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/InditexTech/mcp-server-simulator-ios-idb'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/inditextech--mcp-server-simulator-ios-idb/badge.svg)](/listings/inditextech--mcp-server-simulator-ios-idb)

HTML

<a href="/listings/inditextech--mcp-server-simulator-ios-idb"><img src="/api/listings/inditextech--mcp-server-simulator-ios-idb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The easiest way to install this server is through Cline:

1. Simply ask Cline:

Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb

2. Cline will handle the installation process automatically, including dependency management and configuration.

Alternatively, you can install it manually:

# 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 installation process will automatically: 1. Check if you're running macOS 2. Install idb-companion via Homebrew 3. Install fb-idb via pip in the virtual environment

Note: Make sure to keep the virtual environment activated while using the server. If you close your terminal and come back later, you'll need to reactivate the virtual environment with the `source venv/bin/activate` command before running `npm start`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 421 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 📱 MCP Server for iOS Simulator
  2. [![MCP Server](https://glama.ai/mcp/servers/@InditexTech/mcp-server-simulator-ios-idb/badge)](https://glama.ai/mcp/servers/@InditexTech/mcp-server-simulator-ios-idb)
  3. A Model Context Protocol (MCP) server that enables LLMs to interact with iOS simulators through natural language commands.
  4. ## ℹ️ Overview
  5. This MCP server provides a bridge between Large Language Models (LLMs) and iOS simulators, offering comprehensive control through natural language commands. Here's what it can do:
  6. For detailed usage, see the Installation guide and Supported Commands sections. You can use this server either through direct MCP integration or as a standalone library.
  7. Check out the Architecture section to understand how the components work together to enable natural language control of iOS simulators. For the full execution flow, component contracts, and the session model, see [ARCHITECTURE.md](ARCHITECTURE.md). Guidance for agents and contributors working on this repository is in [AGENTS.md](AGENTS.md).
  8. ![demo](demo/demo.gif)
  9. ### 🎮 Simulator Control
  10. - Create and manage simulator sessions
  11. - Boot, shutdown, and monitor simulator states
  12. - List available and running simulators
  13. - Focus simulator windows
  14. ### 📱 Application Management
  15. - Install and manage iOS applications
  16. - Launch, terminate, and uninstall apps
  17. - Monitor app states and verify installations
  18. - Handle app permissions and configurations
  19. ### 🖱️ UI Interaction & Testing
  20. - Interact with the simulator UI
  21. - Execute tap, swipe, and button press actions
  22. - Input text and key sequences
  23. - Access accessibility elements for UI testing
  24. - Record videos of UI interactions
  25. ### 🛠️ Development & Debugging
  26. - Capture screenshots and system logs
  27. - Debug applications in real-time
  28. - Monitor and analyze crash logs
  29. - Install dynamic libraries and manage app data
  30. ### ⚡ Advanced Features
  31. - Additional functionality includes:
  32. - Location simulation
  33. - Media injection
  34. - URL scheme handling
  35. - Contact database management
  36. - Keychain operations
  37. For detailed usage, see the Installation guide and Supported Commands sections. You can use this server either through direct MCP integration or as a standalone library.
  38. Check out the Architecture section to understand how the components work together to enable natural language control of iOS simulators.
  39. ## 📋 Requirements
  40. - **macOS**: 15 or later on Apple Silicon (arm64), required by idb
  41. - **Node.js**: v24.22.1 LTS or later (CI uses 24.22.1)
  42. - **npm**: v12.2.0 (install with `npm install --global npm@12.2.0` after selecting Node)
  43. - **Homebrew**: Required for installing dependencies
  44. - **Xcode**: 26 or later, selected as the active developer directory, with iOS simulators installed
  45. ## 🚀 Installation
  46. The easiest way to install this server is through Cline:
  47. 1. Simply ask Cline:
  48. ```
  49. Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb
  50. ```
  51. 2. Cline will handle the installation process automatically, including dependency management and configuration.
  52. Alternatively, you can install it manually:
  53. ```bash
  54. # Clone the repository
  55. git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
  56. cd mcp-server-simulator-ios-idb
  57. # Install the locked dependencies (also installs native idb dependencies)
  58. npm ci
  59. # Check TypeScript, including tests
  60. npm run typecheck
  61. # Build the project
  62. npm run build
  63. # Start the project
  64. npm start
  65. # Run tests
  66. npm test
  67. # Run opt-in integration tests against a real, disposable simulator
  68. # (never touch your existing simulators; requires idb + Xcode locally)
  69. npm run test:integration
  70. ```
  71. The installation process will automatically:
  72. 1. Check macOS 15+, Apple Silicon, Homebrew and Xcode 26+ prerequisites
  73. 2. Install the official `meta/fb/idb` Homebrew metapackage, which provides matching client and companion versions (currently 1.7.8); on Homebrew versions with trust controls, trust only the `idb`, `idb-cli` and `idb-companion` formulae
  74. 3. Verify the effective executable paths and versions
  75. Python and its dependencies are managed by Homebrew; no project virtual environment is needed. If migrating from the old installation, deactivate the old venv and ensure Homebrew's `bin` directory is on the PATH used by your terminal and MCP host. The installer rejects executables that shadow Homebrew's installation; it does not delete the old venv.
  76. Homebrew follows the current stable tap rather than `package-lock.json`. Record the installed versions with `brew list --versions meta/fb/idb meta/fb/idb-cli meta/fb/idb-companion`. To update an existing native installation, run `brew update && brew upgrade meta/fb/idb meta/fb/idb-cli meta/fb/idb-companion`, then rerun `npm ci` to verify it.
  77. If you installed `idb` from the older `facebook/fb` tap (GitHub renamed the `facebook` organization to `meta`), Homebrew refuses to install the same formula names from `meta/fb`. The installer detects this from the installed receipts, changes nothing and stops with instructions. Migrate once, then rerun the installation (the installer re-establishes formula trust for `meta/fb/idb`, `meta/fb/idb-cli` and `meta/fb/idb-companion`):
  78. ```bash
  79. brew uninstall idb idb-cli idb-companion
  80. npm ci
  81. ```
  82. ## 🔌 MCP Integration
  83. To use this server with Claude or other LLM assistants:
  84. 1. Add the server to your MCP settings in Claude Desktop:
  85. ```json
  86. {
  87. "mcpServers": {
  88. "ios-simulator": {
  89. "command": "node",
  90. "args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
  91. "env": {}
  92. }
  93. }
  94. }
  95. ```
  96. 2. The LLM can now use natural language commands to control iOS simulators:
  97. ```
  98. create a simulator session with iPhone 14
  99. install app /path/to/my-app.ipa
  100. launch app com.example.myapp
  101. tap at 100, 200
  102. take a screenshot
  103. ```
  104. ## 📚 Usage as a Library
  105. You can also use this package as a library in your own projects:
  106. ### 🔰 Basic Usage
  107. > ⚠️ **Import side effects**: importing the package entry point
  108. > (`'mcp-server-simulator-ios-idb'` / `dist/index.js`) runs the server startup
  109. > code at module load: it overrides console output, creates a `logs/`
  110. > directory, registers `SIGINT`/`SIGTERM`/exception handlers, and **starts the
  111. > MCP stdio server unconditionally**. There is currently no opt-out. This
  112. > applies to *any* import of the package root — named imports do not opt out
  113. > of the bootstrap. To use the parser/orchestrator/manager without transport
  114. > and signal side effects, import the compiled component modules by **deep
  115. > path** as shown below (`dist/...`); note that importing
  116. > `dist/mcp/mcp-server.js` also bootstraps the MCP server singleton, so avoid
  117. > that path for library use. The package only declares `"main"` (no `exports`
  118. > map), so deep paths resolve normally.
  119. ```typescript
  120. // Deep imports of compiled component modules: these do NOT trigger the
  121. // package root startup (no MCP stdio server, no signal handlers).
  122. import { MCPOrchestrator } from 'mcp-server-simulator-ios-idb/dist/orchestrator/MCPOrchestrator.js';
  123. import { NLParser } from 'mcp-server-simulator-ios-idb/dist/parser/NLParser.js';
  124. import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';
  125. async function main() {
  126. // Compose the components (equivalent to createMCPServer internals)
  127. const idbManager = new IDBManager();
  128. const parser = new NLParser();
  129. const orchestrator = new MCPOrchestrator(parser, idbManager);
  130. // Process natural language commands
  131. // Create a simulator session
  132. const sessionResult = await orchestrator.processInstruction('create session');
  133. console.log(`Session created: ${sessionResult.data}`);
  134. // Interact with the simulator
  135. await orchestrator.processInstruction('tap at 100, 200');
  136. // Capture a screenshot
  137. const screenshotResult = await orchestrator.processInstruction('take screenshot');
  138. console.log(`Screenshot saved at: ${screenshotResult.data}`);
  139. }
  140. main().catch(console.error);
  141. ```
  142. > ℹ️ The MCP server itself (currently defined in `src/mcp/mcp-server.ts`, not
  143. > re-exported from the package entry point) is only meaningful when running
  144. > the actual server process via `npm start` / an MCP client config; its
  145. > `createMCPServer()` factory simply composes the same three components shown
  146. > above.
  147. ### 🚀 Advanced Usage
  148. You can also use the individual components directly via deep imports:
  149. ```typescript
  150. import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';
  151. // Create instance and use it directly
  152. const idbManager = new IDBManager();
  153. const sessionId = await idbManager.createSimulatorSession({
  154. deviceName: 'iPhone 12',
  155. platformVersion: '15.0'
  156. });
  157. await idbManager.tap(sessionId, 100, 200);
  158. ```
  159. ## 🏗️ Project Structure
  160. ```
  161. mcp-server-simulator-ios-idb/
  162. ├── src/ # Source code
  163. │ ├── adapters/ # Adapter components
  164. │ ├── idb/ # IDB manager implementation
  165. │ ├── mcp/ # MCP server implementation
  166. │ ├── orchestrator/ # Command orchestrator
  167. │ ├── parser/ # Natural language parser
  168. │ └── index.ts # Main entry point
  169. ├── scripts/ # Installation scripts
  170. ├── package.json # Project configuration
  171. └── tsconfig.json # TypeScript configuration
  172. ```
  173. ## 🎯 Supported Commands
  174. The NLParser supports the following natural language commands:
  175. ### 🎮 Simulator Management
  176. | Command | Description | Example |
  177. |---------|-------------|---------|
  178. | Create session | Creates a new simulator session | "create session", "create simulator iPhone 12" |
  179. | Terminate session | Terminates the current session | "terminate session", "close simulator" |
  180. | List simulators | Lists available simulators | "list simulators", "show simulators" |
  181. | List booted simulators | Lists running simulators | "list booted simulators", "show running simulators" |
  182. | Boot simulator | Boots a simulator by UDID | "boot simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2" |
  183. | Shutdown simulator | Shuts down a simulator | "shutdown simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2" |
  184. | Focus simulator | Brings simulator window to front | "focus simulator", "bring simulator to front" |
  185. | Check simulator | Checks if the current simulator session is booted | "check simulator", "is simulator booted" |
  186. | List simulator sessions | Lists active simulator sessions | "list simulator sessions", "show active sessions" |
  187. ### 📱 App Management
  188. | Command | Description | Example |
  189. |---------|-------------|---------|
  190. | Install app | Installs an app on the simulator | "install app /path/to/app.ipa" |
  191. | Launch app | Launches an app on the simulator | "launch app com.example.app" |
  192. | Terminate app | Terminates a running app | "terminate app com.example.app" |
  193. | Uninstall app | Uninstalls an app | "uninstall app com.example.app" |
  194. | List apps | Lists installed applications | "list apps", "show installed apps" |
  195. | Check if app installed | Checks if an app is installed | "is app com.example.app installed", "check app com.example.app" |
  196. ### 🖱️ UI Interaction
  197. | Command | Description | Example |
  198. |---------|-------------|---------|
  199. | Tap | Taps at specific coordinates | "tap at 100, 200" |
  200. | Swipe | Performs a swipe gesture | "swipe from 100, 200 to 300, 400" |
  201. | Press button | Presses a device button | "press button HOME", "press button SIRI" |
  202. | Input text | Types text | "input text Hello World" |
  203. | Press key | Presses a key by code | "press key 4" |
  204. | Press key sequence | Presses a sequence of keys | "press key sequence 4 5 6" |
  205. ### ♿ Accessibility
  206. | Command | Description | Example |
  207. |---------|-------------|---------|
  208. | Describe elements | Lists all accessibility elements (not implemented yet) | "describe all elements", "show accessibility elements" |
  209. | Describe point | Describes element at coordinates (not implemented yet) | "describe point 100, 200", "what's at 150, 300" |
  210. ### 📸 Capture and Logs
  211. | Command | Description | Example |
  212. |---------|-------------|---------|
  213. | Take screenshot | Captures a screenshot | "take screenshot", "capture screen" |
  214. | Record video | Records screen activity (not implemented yet) | "record video /path/output.mp4" |
  215. | Stop recording | Stops video recording (not implemented yet) | "stop recording", "stop video recording" |
  216. | Get logs | Retrieves system or app logs | "get logs", "get logs for com.example.app" |
  217. Omitting `outputPath` (plain "take screenshot") returns native MCP `image/png` content instead of a JSON Buffer.
  218. ### 🐛 Debug
  219. | Command | Description | Example |
  220. |---------|-------------|---------|
  221. | Start debug | Starts a debug session (not implemented yet) | "debug app com.example.app", "start debug com.example.app" |
  222. | Stop debug | Stops a debug session (not implemented yet) | "stop debug", "terminate debug session" |
  223. | Debug status | Gets debug session status | "debug status", "show debug info" |
  224. ### 💥 Crash Logs
  225. | Command | Description | Example |
  226. |---------|-------------|---------|
  227. | List crash logs | Lists available crash logs | "list crash logs", "show crash logs" |
  228. | Show crash log | Shows content of a crash log | "show crash log crash_2023-01-01" |
  229. | Delete crash logs | Deletes crash logs of an app, or all of them when asked explicitly | "delete crash logs for com.example.app", "delete all crash logs" |
  230. ### 🔧 Additional Commands
  231. | Command | Description | Example |
  232. |---------|-------------|---------|
  233. | Install dylib | Installs a dynamic library | "install dylib /path/to/library.dylib" |
  234. | Open URL | Opens a URL in the simulator | "open url https://example.com" |
  235. | Clear keychain | Clears the simulator's keychain | "clear keychain" |
  236. | Set location | Sets the simulator's location | "set location 37.7749, -122.4194" |
  237. | Add media | Adds media to the camera roll | "add media /path/to/image.jpg" |
  238. | Approve permissions | Approves app permissions | "approve permissions com.example.app photos camera" |
  239. | Update contacts | Updates contacts database | "update contacts /path/to/contacts.sqlite" |
  240. The interface supports all commands available in the idb CLI tool, providing a comprehensive set of operations for iOS simulator automation.
  241. ## 🔍 Architecture
  242. The server consists of three main components:
  243. 1. **IDBManager**: Low-level component that interacts directly with iOS simulators through idb.
  244. 2. **NLParser**: Component that interprets natural language instructions and converts them into structured commands.
  245. 3. **MCPOrchestrator**: Central component that coordinates interactions between the parser and the IDBManager.
  246. These components are connected through adapters:
  247. - **ParserToOrchestrator**: Converts parser results into orchestrator commands.
  248. - **OrchestratorToIDB**: Translates orchestrator commands into IDBManager calls.
  249. The complete execution flow (MCP stdio → orchestrator → parser/registry → adapters → IDBManager → `idb` / `xcrun simctl`), component contracts, the session model (`activeSessionId` vs `sessionId → UDID`), and a checklist for adding new commands are documented in [ARCHITECTURE.md](ARCHITECTURE.md).
  250. ## 🔌 MCP Integration
  251. To use this server with the Model Context Protocol:
  252. 1. Add the server to your MCP settings:
  253. ```json
  254. {
  255. "mcpServers": {
  256. "ios-simulator": {
  257. "command": "node",
  258. "args": ["/path/to/mcp-server-simulator-ios-idb/dist/index.js"],
  259. "env": {}
  260. }
  261. }
  262. }
  263. ```
  264. 2. Connect to the server in your LLM application:
  265. ```typescript
  266. const result = await useMcpTool({
  267. serverName: "ios-simulator",
  268. toolName: "process-instruction",
  269. arguments: {
  270. instruction: "create simulator session"
  271. }
  272. });
  273. ```
  274. ## 🧪 Testing
  275. ### Mocked unit tests (default)
  276. `npm test` runs only the mocked unit suites under `src/**/__tests__/`. They
  277. never create, boot, or modify any simulator:
  278. - `CommandWiring.test.ts` asserts a hand-written canonical table: every parser
  279. example reaches exactly one `IDBManager` method with exact arguments, and no
  280. other method is called. Unsupported commands fail with
  281. `Command not supported by the IDB manager: <method>` and zero manager calls.
  282. - `CommandRegressionMatrix.test.ts` covers each regression class fixed by
  283. PR #71 (exact command mapping, case/leading-zero preservation, earliest and
  284. longest parser match, explicit crash-log deletion scope, session threading).
  285. - `IDBManager.test.ts` pins the `idb` / `xcrun simctl` argv, response, and
  286. error contracts of the newly wired commands. These are **wiring contracts
  287. only**: passing here does not prove the real CLI accepts those arguments.
  288. ### Opt-in integration tests (real simulator)
  289. ```bash
  290. npm run test:integration
  291. ```
  292. Runs only with the dedicated Jest config (`jest.integration.config.js`) and
  293. `IOS_SIM_INTEGRATION=1`; it is never enabled by `npm test` or CI. The suite:
  294. 1. Creates exactly **one disposable simulator** named `mcp-integration-<id>`
  295. from an available runtime/device pair (polled for real `Booted` state —
  296. no blind sleeps).
  297. 2. Drives the full stack through the **real MCP protocol**: spawns
  298. `dist/index.js` and speaks JSON-RPC over stdio with the MCP SDK Client
  299. (transport → parser → adapters → `IDBManager` → `idb`/`simctl`).
  300. 3. Asserts observable effects: owned device in the inventory, accurate booted
  301. listing, PNG signature of screenshots, Safari launch/list/terminate,
  302. URL opening through the fixture's own `mcpfixture://` scheme (the app
  303. renders the URL it receives via `onOpenURL`; no external network), and
  304. uninstall/`bundleId` truthfulness with a compiled fixture app
  305. (`com.inditex.mcp.fixture.demo`).
  306. 4. Verifies unsupported commands fail honestly over the wire.
  307. 5. Guarantees cleanup: teardown shuts down and deletes the owned device by
  308. its exact UDID even when tests fail, and terminates the `idb_companion`
  309. process spawned for the owned UDID (exact argv match, current user only,
  310. PID-reuse fail-closed) plus its `/tmp/idb/<udid>` socket. Existing
  311. simulators and other users' processes are never touched; every run
  312. asserts their recorded pre-run state is unchanged.
  313. 6. Captures nothing sensitive: the run reads no real crash logs (a crash
  314. command smoke was removed on purpose — on current runtimes the CLI mixes
  315. host operating-system crash reports into per-device output, so a real
  316. smoke would ingest sensitive host data; the command's parsing contract
  317. is covered by synthetic unit tests instead), and CI failure artifacts
  318. whitelist only the suite-owned artifacts directory (screenshots captured
  319. by the suite and the sanitized run summary); the generic `logs/` output
  320. of the server is never uploaded.
  321. Requires `idb` and `fb-idb` already installed (`npm ci` on macOS). The run
  322. takes several minutes (simulator boot + fixture build).
  323. ## 🙏 Acknowledgments
  324. This project would not be possible without [facebook/idb](https://github.com/facebook/idb), which provides the underlying iOS simulator control capabilities. We extend our sincere gratitude to the Facebook/Meta team and all contributors to the idb project for creating and maintaining such a powerful and reliable tool.
  325. ## 📄 License
  326. This tool is available as open source under the terms of the Apache-2.0.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.