# simulator-use

simulator-use — an MCP server that lets a coding agent build an Xcode project, read the iOS Simulator screen as plain text, and tap elements by their label.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6 repo stars
- Author: NoMac-app
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/NoMac-app/simulator-use
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/simulator-use

## What it does

simulator-use builds and launches an Xcode project, then turns the simulator screen into a handful of text lines instead of a full accessibility tree, so the agent can tap or type into a field by its `#id` or label. A `tests_run` tool runs unit and UI tests case by case and reports failures with file and line. The server talks to the Simulator through its own engine rather than spinning up a helper process on every call.

\`ui_act` steps such as `tap`, `fill`, `scroll`, `swipe` and `wait` run in sequence, and each one is checked: typed text gets read back from the field, and a tap that produces no visible change is flagged rather than silently accepted. Web content inside UIKit apps (Capacitor, React Native's WebView) is read line by line, but pages inside a SwiftUI WebView, Safari, or in-app browsers have nothing for accessibility to read, so those screens need a screenshot and tap-by-point instead.

It needs a Mac with Xcode installed for local builds; from Linux, Windows, or a Mac without Xcode, `npx simulator-use cloud start` opens a cloud iPhone instead.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add simulator-use -- npx -y simulator-use
```

### Codex

**Platform CLI**
```bash
codex mcp add simulator-use -- npx -y simulator-use
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "simulator-use": {
            "command": "npx",
            "args": [
                "-y",
                "simulator-use"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "simulator-use": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "simulator-use"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add simulator-use npx -y simulator-use
```

## When to use it
- build and launch an Xcode project from an agent session
- read an app screen as text instead of a screenshot
- tap and fill fields by accessibility id rather than coordinates
- run XCTest and XCUITest case by case with failure line numbers
- reach a Simulator from Linux or Windows through a cloud iPhone

## Example prompts
- Build the Xcode project and show me the first screen
- Fill #email with test@example.com and tap #signIn
- Run the tests and tell me which ones failed

## Similar
- [limrun-ios-simulator](https://affpapa.org/en/nevibecode/skills/limrun-ios-simulator.md) — skill · 45300 installs
- [ios-simulator](https://affpapa.org/en/nevibecode/skills/dpearson2699-ios-simulator.md) — skill · 3400 installs
- [ios-simulator-skill](https://affpapa.org/en/nevibecode/skills/ios-simulator-skill.md) — skill · 2500 installs
- [argent-ios-simulator-setup](https://affpapa.org/en/nevibecode/skills/argent-ios-simulator-setup.md) — skill · 32700 installs
- [eas-simulator](https://affpapa.org/en/nevibecode/skills/eas-simulator.md) — skill · 25500 installs
- [ios-simulator-browser](https://affpapa.org/en/nevibecode/skills/ios-simulator-browser.md) — skill · 53 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
