SimGadget boots simulators, reads the accessibility tree, and taps controls by name — from TypeScript, or from any AI agent that speaks MCP. No Python, no Homebrew, no four-year-old tooling.
macOS on Apple Silicon · Xcode with iOS simulators · Node 18+.
You do not install idb_companion — SimGadget brings its own.
SimGadget is a TypeScript library for driving iOS simulators, and an MCP server built on it that lets a fleet of AI agents each drive their own simulator at once.
The alternatives shell out to the Python idb CLI, or to Homebrew's
idb_companion — last released in 2022 — or to xcrun simctl,
which cannot read accessibility at all.
SimGadget ships its own idb_companion, built from current upstream source
against current Xcode, pinned by sha256 and fetched on first use. Everything above it
was rewritten on top of that.
A tap costs ~1.2 ms of wire time instead of the ~165 ms it takes to spawn a Python process for every single call. Finding a control by name is ~13 ms on the fast path. A whole screen is ~350 ms. Asking what is at a point is ~10 ms.
The whole design is shaped by that: tap({label: "Sign Up"}) resolves the
element on the simulator and operates it, so nothing ever pulls down a
kilobyte-scale tree just to find one button.
The library has exactly two npm runtime dependencies:
@grpc/grpc-js and @bufbuild/protobuf. That's it.
No test framework leaking into your install, no CLI wrappers, no 14 MB of
transitive weight.
That is also why there are two packages. The MCP SDK and Zod are 14 MB between them, and a library that taps a simulator has no business putting them in front of you.
SimGadget pins a build from current idb source against Xcode 26.6 / Swift 6.3.3, sha256-verified, downloaded once and cached.
This is not housekeeping — it is what makes the rest possible. Tap-by-name doesn't work on the old companion. Neither does reading the contents of a tab bar, a nav bar or a toolbar.
There is deliberately no fallback to whatever idb_companion is on
your $PATH: an old companion doesn't reject request fields it
doesn't understand, it ignores them and answers anyway. A fallback would return results
that are wrong but entirely plausible.
A long list of failures that cost real debugging time to find, each of them the kind that reports success while doing nothing. Instant taps that don't register. Switches that were never tappable. System sheets landing taps 476 points away. Simulators that wedge on boot.
Every one is measured, and every measurement traces to a run in the repository.
You have a shell and a Node runtime. You don't need a protocol between you and a simulator.
Because we support labels, tapping, typing, scrolling, it's all reproducable, even if you alter the exact place of the elements.
import { createSimulator } from "simgadget";
const sim = await createSimulator({
deviceType: "iPhone 16 Pro",
});
await sim.installApp("./build/MyApp.app");
await sim.launchApp("com.example.myapp");
await sim.tap({ label: "Sign Up" });
await sim.typeText("test@example.com");One server. Many agents. Many simulators. Nobody steps on anybody.
› ui_tap { id: "qa1", label: "Sound" }
‹ Toggled Sound off -> on.
› ui_tap { id: "qa1", label: "Stepper" }
‹ Refused: "Stepper" is covered by
"Search" (SearchField) at (102, 96).simgadget | simgadget-mcp | |
|---|---|---|
| For | TypeScript / JavaScript code | AI agents — Claude Code, Cursor, anything MCP |
| Install | npm install simgadget | npx -y simgadget-mcp |
| Runtime deps | 2 | 4 |
| Gives you | Simulator handle, typed results, typed errors | 17 tools, sessions, multi-agent isolation |
xcrun simctl, sips
and tar, which ship with macOS. You do not install
idb_companion — SimGadget fetches a pinned one on first use, or run
npx simgadget prefetch if you'd rather front-run the download in CI.
$PATH is deliberately ignored — a
silent fallback to a 2022 binary would be worse than none, because it answers wrong
instead of erroring.npm install simgadget, then
see the library page.npx -y simgadget-mcp, then
point your agent at it — setup here.ios-simulator-mcp?ios-simulator-mcp and has
diverged substantially — different transport, different lifecycle model, its own
companion, and a library underneath. The foundational work is his and is credited.
No pipx install fb-idb. No brew install idb-companion.
No Xcode command-line archaeology.