# baepsae [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/oozoofrog/mcp-baepsae  
**GitHub Stars:** 26  
**npm Downloads (last month):** 254  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/baepsae

## Description
Local MCP server for iOS Simulator and macOS app automation with a native Swift bridge

## Tools
Capabilities this server exposes over MCP:

- **baepsae_help** — Show help. Optionally pass subcommand name for compatibility reference.
- **baepsae_version** — Show server and native binary versions.
- **doctor** — Run readiness self-checks for host process, parent process, native binary, booted simulator availability, and accessibility permission.
- **list_apps** — List running macOS applications with their bundle IDs.
- **get_focused_app** — Get information about the currently focused macOS app.
- **list_simulators** — List available simulators using simctl.
- **open_url** — Open a URL in the simulator (e.g. Safari or deep link).
- **install_app** — Install an app (.app, .ipa) on the simulator.
- **uninstall_app** — Uninstall an app from the simulator.
- **launch_app** — Launch an installed app on the simulator.
- **terminate_app** — Terminate a running app on the simulator.
- **analyze_ui** — Describe app UI hierarchy. Works with both simulator (udid) and macOS (bundleId/appName) targets.
- **query_ui** — Search app UI elements by text, identifier, or label. Works with both simulator and macOS targets.
- **tap** — Tap coordinates or accessibility element. Selector lookup defaults to in-app content; set all=true to include Simulator chrome UI.
- **type_text** — Type text into the target app. auto resolves to paste for all targets (more reliable for CJK and emoji); simulator paste uses the simulator pasteboard, macOS paste temporarily uses the host clipboard; keyboard types character-by-character.
- **swipe** — Perform swipe gesture in the target app.
- **scroll** — Send scroll wheel events to the target app.
- **drag_drop** — Drag and drop in the target app.
- **tap_tab** — Tap a tab in a tab bar by index. Prefers semantic descendants or top-row semantic proxy buttons when available, and falls back to geometry only when needed. Useful for SwiftUI TabView cases where tab buttons are not cleanly exposed.
- **wait_for_ui** — Wait for a UI element to appear or disappear. Polls query_ui at interval until condition met or timeout.
- **detect_dialog** — Detect if a modal dialog, sheet, or alert is currently presented. Returns JSON with hasDialog, type, title, isModal, and buttons.
- **set_ui_value** — Set value, text selection range, or focus on a UI element via Accessibility API.
- **read_ui_param** — Read parameterized accessibility attributes like text ranges, line numbers, and bounds.
- **read_ui_value** — Read value, selected text, or insertion point of a UI element via Accessibility API.
- **hit_test** — Find which UI element is at specific screen coordinates. Uses system-wide accessibility hit testing. No app target needed.
- **enumerate_ui** — Discover all attributes, actions, and parameterized attributes of a UI element. Shows which attributes are settable.
- **button** — Press a simulator hardware button.
- **key** — Press a single HID keycode in the target app.
- **key_sequence** — Press multiple HID keycodes in sequence in the target app.
- **key_combo** — Press key combo in the target app.
- **touch** — Perform touch events in the target app.
- **gesture** — Execute a preset gesture pattern.
- **input_source** — Get current keyboard input source or switch to a specific one. Call without sourceId to query current; with sourceId to switch. Uses CJKV workaround for Korean/Japanese/Chinese/Vietnamese.
- **list_input_sources** — List all available keyboard input sources with their IDs, names, and active status.
- **run_steps** — Execute ordered workflow steps using existing tap, type_text, key, swipe, and sleep behavior. Defaults to fail-fast; set continueOnError or continue_on_error to keep going after a failure.
- **stream_video** — Capture a time-bounded simulator clip through the native stream-video shim.
- **record_video** — Record simulator display directly with simctl recordVideo.
- **screenshot** — Capture a screenshot from simulator display using simctl screenshot.
- **list_windows** — List windows in the target app.
- **activate_app** — Bring the target app to foreground.
- **screenshot_app** — Take a screenshot of the target app window.
- **right_click** — Right-click in the target app. Selector lookup defaults to in-app content; set all=true for Simulator chrome UI.
- **menu_action** — Execute a menu bar action in a macOS app.
- **clipboard** — Read or write the system clipboard.
- **focus_window** — Raise and focus a specific window by index or title. macOS apps only.
- **context_menu_action** — Select an item from an open context menu. Call after right_click. Supports submenu paths with > separator (e.g. 'Refactor > Rename').
- **watch_notification** — Watch for AX notifications from an app. Blocks until a notification fires or timeout. Use presets for common patterns: window (created/destroyed), text (value/selection changed), focus (app/window focus), menu (opened/closed).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "baepsae": {
    "command": "npx",
    "args": ["-y","mcp-baepsae@latest"],
    "env": {
      "BAEPSAE_NATIVE_PATH": ""
    }
  }
}
```

**Requires environment variables:** `BAEPSAE_NATIVE_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What baepsae MCP server does

The baepsae MCP server provides local automation for iOS Simulator and macOS applications through the Model Context Protocol. Its currently listed MCP tools are `paste` and `keyboard`, allowing an MCP client to send text or keyboard input to the local automation environment.

The project is intended for macOS-based development workflows. It targets iOS Simulator sessions and macOS apps rather than remote devices or cloud-hosted systems. The implementation has two parts: a TypeScript MCP layer that handles the server interface and a Swift native bridge for macOS automation functions.

This setup fits workflows where an agent needs to enter text or control keyboard input while testing or interacting with a simulator or desktop application. It is not a cross-platform MCP server: Linux and Windows are unsupported because the native component depends on macOS frameworks and the Xcode `xcrun simctl` command.

## How it works

The server runs locally and communicates with an MCP client over its configured runtime. The TypeScript portion is started through a local build, an npm package, `npx`, or another supported JavaScript runtime. When native functionality is available, the Swift bridge handles macOS-specific operations using AppKit, CoreGraphics, and Accessibility frameworks.

The native binary is built as part of the npm installation when Swift is available. A source checkout can also build the TypeScript server and Swift component together. If Swift is unavailable during npm installation, simctl-based functionality can still operate, but native features that depend on the Swift binary may not be available.

## Setup and configuration

Use macOS 14 or later, Xcode or Xcode Command Line Tools, Node.js 18 or newer, and Swift 6 or newer. The simplest installation is `npx mcp-baepsae@latest`; alternatively, install the package globally with npm or clone the repository and run `npm install` followed by `npm run build`.

The repository includes an installer that can register the server with supported MCP clients. Its runtime choices include a local Node build, `npx`, `bunx`, and a globally installed command. The installer can also preview changes, check dependencies, or remove registrations.

For a local build, `BAEPSAE_NATIVE_PATH` can point the MCP configuration to the compiled `baepsae-native` executable. This is useful when the TypeScript server and native binary are built from source.

## Tools and capabilities

- `paste`: provides a tool for paste-oriented local automation.
- `keyboard`: provides a tool for keyboard input automation.
- iOS Simulator support through macOS and Xcode tooling.
- macOS application automation through the native Swift bridge.

The baepsae MCP server may require Accessibility permission for input automation. Grant permission to the process that actually launches it, such as the MCP client, terminal, Node runtime, or native binary. After changing permissions, restart the relevant launching process if macOS does not apply the change immediately.

## Limitations and notes

The baepsae MCP server requires macOS and does not support Linux or Windows. iOS Simulator use also depends on Xcode or its Command Line Tools. Simulator-specific commands rely on `xcrun simctl`, while native automation relies on macOS-only frameworks.

Permission failures may come from the host process rather than the target application. Check the MCP client or terminal, the runtime such as `node`, and `baepsae-native` when it is invoked directly.

_Full upstream README: https://allmcps.com/mcp/baepsae/readme_