mcp-baepsae

Baepsae (Vinous-throated Parrotbill) — A tiny Korean bird. Round, chubby, and constantly hopping around chirping. Known for its grit — even when a little bird tries to keep up with a stork, it never gives up. This project is small too, but it pecks away at your simulators tirelessly.

Local MCP server for iOS Simulator and macOS app automation with a TypeScript MCP layer and a Swift native bridge.

한국어 문서는 README-KR.md를 참고하세요.

Table of Contents

• Prerequisites
• Platform Support
• Install
• Permissions
• MCP Setup (Recommended)
• Client Matrix
• For LLM
• Manual Setup (Fallback)
• Project Structure
• Commands
• MCP Tool Status
• Usage Examples
• Troubleshooting

Prerequisites

• macOS 14+
• Xcode + iOS Simulator
• Node.js 18+
• Swift 6+

Platform Support

Why macOS only?

The Swift native bridge (baepsae-native) uses macOS-specific frameworks (AppKit, CoreGraphics, Accessibility) to interact with iOS Simulator and macOS applications. These frameworks are not available on Linux or Windows. The TypeScript MCP layer also relies on xcrun simctl, which is part of Xcode Command Line Tools and only available on macOS.

Requirements summary:

• macOS 14 or later -- required for iOS Simulator automation and Accessibility API access.
• Xcode or Xcode Command Line Tools -- required for Swift 6+ compilation of the native binary and xcrun simctl commands.
• Node.js >= 18.0.0 -- required to run the TypeScript MCP server.

Permissions

Accessibility permission is required for UI inspection and input automation features (use unified generic tools such as analyze_ui, tap, right_click).

The important detail is that permission usually needs to be granted to the automation host / runtime process, not to the target app you are automating.

Which process usually needs permission?

• Direct native binary invocation
  • Example: baepsae-native ...
  • Most relevant entry: the baepsae-native binary itself, plus the terminal/shell app that launched it
• Node / npx MCP runtime
  • Example: node dist/index.js, npx -y mcp-baepsae@latest
  • Most relevant entry: the runtime process (node), plus the terminal or MCP client app that launched it
• Desktop / CLI MCP clients
  • Example: Claude Code, Codex CLI/Desktop, Gemini CLI
  • Relevant entries can include the MCP client app, the terminal host, and the runtime process depending on launch path

Recommended setup flow

1. Open System Settings > Privacy & Security > Accessibility.
2. Enable the terminal or MCP client app you actually use.
3. Enable the runtime process if listed (node, bun, etc.).
4. For direct native invocation, also enable the baepsae-native binary entry if it appears separately.
5. If an entry is missing, click + and add it manually.

Important note

After granting permission, the launching process may need to be restarted before macOS applies the change.
If the error persists, quit and relaunch the terminal, MCP client, or runtime process that started mcp-baepsae.

For simulator targets, selector-based actions (tap / right_click with id or label) search in-app content by default. Set all: true to include Simulator chrome UI.

Install

Option A) npm (easiest)

# Run directly without installing
npx mcp-baepsae@latest

# Or install globally
npm install -g mcp-baepsae

On macOS, the Swift native binary is built automatically during install. If Swift is not available, the server still works with simctl-based features.

If you plan to use UI inspection or input automation right away, grant Accessibility permission to the terminal / MCP client / runtime process you will actually launch the server with.

Option B) From source

git clone https://github.com/oozoofrog/mcp-baepsae.git
cd mcp-baepsae
npm install
npm run build

MCP Setup (Recommended)

Use the installer script that calls each client's MCP install flow directly.

bash scripts/install.sh --tool all

Client Matrix

For LLM

If you are an LLM agent setting up this MCP server, here is everything you need:

Before trying UI automation tools, remember that Accessibility permission usually belongs to the host/runtime process (node, terminal, MCP client), not the target app under automation.

Quick start (one command)

# Register baepsae as an MCP server for all supported clients
bash scripts/install.sh --tool all

If you installed via npm instead of cloning the repo, use npx:

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

Automation flags

# Preview commands without executing
bash scripts/install.sh --tool all --dry-run

# Verify environment and dependencies
bash scripts/install.sh --tool all --doctor

# Unregister from all clients
bash scripts/install.sh --tool all --uninstall

Runtime options

The installer supports multiple runtimes via --runtime:

Manual Setup (Fallback)

Use this when you do not want to run scripts/install.sh.

Using npx (recommended for npm users)

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

# Gemini CLI
gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest

When using npx, the relevant Accessibility entry is commonly the spawned node runtime plus the terminal / MCP client that launched it.

Using local build

# Claude Code (project)
claude mcp add --scope project --env="BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native" baepsae -- node /ABS/PATH/dist/index.js

# Codex CLI
codex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native -- node /ABS/PATH/dist/index.js

# Gemini CLI
gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native baepsae node /ABS/PATH/dist/index.js

When using a local build, check permission on both the runtime (node) and the app that launched it.
If you invoke baepsae-native directly for debugging, check permission on the native binary entry itself as well.

Project Structure

• MCP server entry point: src/index.ts
• Tool modules: src/tools/ (info, simulator, ui, input, media, system)
• Shared utilities: src/utils.ts, src/types.ts
• Native binary entry point: native/Sources/main.swift
• Native command handlers: native/Sources/Commands/
• Native binary output: native/.build/release/baepsae-native
• TS tests: tests/mcp.contract.test.mjs, tests/unit.test.mjs, tests/mcp.real.test.mjs
• Swift tests: native/Tests/BaepsaeNativeTests/

Commands

npm run build       # Build TypeScript + native Swift binary
npm test            # Contract/integration tests
npm run test:real   # Real simulator smoke test (requires booted simulator)
npm run test:real:preflight  # Environment diagnostics only
npm run test:real:sim        # iOS simulator phases only (skips Phase 4)
npm run test:real:mac        # macOS Safari phase only
npm run verify      # test + test:real
npm run setup:mcp   # Alias for scripts/install.sh

MCP Tool Status

43 tools implemented end-to-end.

Official public MCP surface: unified generic tools

The public API surface is intentionally single-scheme: use unified generic tools with a target argument, rather than sim_* / mac_* names.