@plaintest/mcp-connect

A Model Context Protocol (MCP) server that enables AI assistants to control iOS Simulators and automate browsers. Combines the power of xcrun simctl, fb-idb, and Puppeteer into a single unified server.

Features

iOS Simulator Tools

• Screenshots: Capture screenshots in various formats (PNG, JPEG, TIFF, BMP, GIF)
• Device Management: List simulators, get info about booted devices
• Gestures: Tap, swipe with duration control (requires fb-idb)
• Input: Type text into focused fields, press system buttons
• Navigation: Open URLs and deep links
• UI Inspection: Get accessibility tree (requires fb-idb)
• Reset: Erase simulator to factory settings

Browser Automation Tools

• Launch & Control: Launch Chrome/Chromium, navigate to URLs
• Screenshots: Capture full page or element-specific screenshots
• DOM Interaction: Click elements, type text, query elements
• Inspection: Get DOM tree, element info, page info
• JavaScript: Execute arbitrary JavaScript in page context
• Metro Bundler: Quick shortcuts for React Native development

Prerequisites

• macOS with Xcode and iOS Simulator
• Node.js >= 18
• Chrome/Chromium for browser automation
• fb-idb (optional, for enhanced iOS gestures)

Installation

Option 1: Quick Install (Recommended)

Run the installer for your MCP client:

# For Claude Code
npx @plaintest/mcp-connect install claude

# For Cursor
npx @plaintest/mcp-connect install cursor

# For Windsurf
npx @plaintest/mcp-connect install windsurf

# For Cline (VS Code)
npx @plaintest/mcp-connect install cline

# For GitHub Copilot (VS Code)
npx @plaintest/mcp-connect install copilot

# Install for all clients at once
npx @plaintest/mcp-connect install --all

Restart your editor and the tools will be available.

Option 2: Global Install

Install globally to have mcp-connect available as a command:

npm install -g @plaintest/mcp-connect

Then configure your MCP client manually:

{
  "mcpServers": {
    "mcp-connect": {
      "command": "mcp-connect"
    }
  }
}

Option 3: Manual Configuration

If you prefer not to install globally, configure your MCP client to use npx:

{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect"]
    }
  }
}

Config file locations:

• Claude Code: Uses claude mcp add command (automatic with install)
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Copilot: ~/Library/Application Support/Code/User/settings.json (under github.copilot.chat.experimental.mcp.servers)

CLI Commands

npx @plaintest/mcp-connect install <client>    # Install config for a client
npx @plaintest/mcp-connect uninstall <client>  # Remove config from a client
npx @plaintest/mcp-connect list                # List supported clients
npx @plaintest/mcp-connect status              # Show installation status
npx @plaintest/mcp-connect help                # Show help

Tool Filtering

By default, mcp-connect auto-detects which tools to enable based on your system:

• iOS Simulator tools: enabled if Xcode/xcrun is installed
• Browser tools: enabled if Chrome/Chromium is found

This reduces context usage and prevents confusion by only exposing relevant tools.

Override Auto-detection

To manually control which tools are enabled, use the --only flag:

npx @plaintest/mcp-connect --only=browser     # Browser tools only
npx @plaintest/mcp-connect --only=simulator   # iOS Simulator tools only
npx @plaintest/mcp-connect --only=all         # Force all tools

To use filtering with an MCP client, update your config:

{
  "mcpServers": {
    "mcp-connect": {
      "command": "npx",
      "args": ["-y", "@plaintest/mcp-connect", "--only=browser"]
    }
  }
}

Available Tools

iOS Simulator Tools (10)

| Tool | Description | |------|-------------| | capture_simulator_screenshot | Capture screenshot with format/mask options | | list_simulators | List all simulators (booted or all) | | get_simulator_info | Get info about currently booted simulator | | tap_screen | Tap at coordinates (x, y) | | swipe | Swipe from (x1, y1) to (x2, y2) with duration | | simulator_type_text | Type text into focused input field | | press_button | Press system button (home, lock, siri, volume) | | open_url | Open URL or deep link in simulator | | erase_simulator | Reset simulator to factory settings | | get_ui_tree | Get accessibility tree (requires fb-idb) |

Browser Automation Tools (14)

| Tool | Description | |------|-------------| | launch_browser | Launch Chrome/Chromium instance | | navigate | Navigate to URL | | capture_screenshot | Capture page or element screenshot | | click_element | Click element by CSS selector | | type_text | Type into input field | | get_page_info | Get URL, title, viewport info | | get_dom_tree | Get HTML structure with depth control | | evaluate_javascript | Execute JS in page context | | query_elements | Find elements by CSS selector | | get_element_info | Get element position, styles, content | | close_browser | Close browser and cleanup | | open_metro_bundler | Open React Native Metro bundler UI | | get_metro_logs | Extract logs from Metro UI | | reload_metro | Trigger Metro reload |

Examples

Take iOS Simulator Screenshot

AI: Use capture_simulator_screenshot to take a screenshot

Navigate and Interact with Browser

AI: Launch browser and navigate to http://localhost:8081
AI: Click the element with selector ".reload-button"
AI: Capture a screenshot

iOS Gesture Automation

AI: Tap the screen at coordinates (200, 400)
AI: Swipe from (200, 600) to (200, 200) over 0.3 seconds
AI: Type "Hello World" into the focused input

Setup for Tap/Swipe Gestures

For tap_screen and swipe to work reliably, install fb-idb:

brew tap facebook/fb
brew install idb-companion

Without fb-idb:

• Tap falls back to AppleScript (less reliable)
• Swipe is not available

Troubleshooting

Chrome not found

Install Google Chrome or set a custom path:

• The server looks for Chrome at standard macOS locations
• Chromium and Chrome Canary are also supported

Simulator not detected

1. Open Xcode > Open Developer Tool > Simulator
2. Boot a simulator
3. Verify: xcrun simctl list devices booted

fb-idb not working

# Reinstall
brew uninstall idb-companion
brew tap facebook/fb
brew install idb-companion

# Verify
which idb

Permission denied for gestures

Grant Accessibility permissions:

1. System Settings > Privacy & Security > Accessibility
2. Add Terminal (or your shell app)
3. Restart your editor

Development

# Clone the repository
git clone https://github.com/plaintest/mcp-connect.git
cd mcp-connect

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Watch mode
npm run dev

License

MIT License - see LICENSE for details.

Author

George Al-Haddad - Plaintest