@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