MCP Connect

🚀 @plaintest/mcp-connect

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

🚀 Quick Start

The @plaintest/mcp-connect is a versatile MCP server that allows AI assistants to interact with iOS Simulators and automate browsers. Before using it, make sure you meet the prerequisites and choose an appropriate installation method.

✨ Features

iOS Simulator Tools

• Screenshots: Capture screenshots in various formats (PNG, JPEG, TIFF, BMP, GIF).
• Device Management: List simulators and get info about booted devices.
• Gestures: Tap, swipe with duration control (requires fb-idb).
• Input: Type text into focused fields and 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 and navigate to URLs.
• Screenshots: Capture full page or element-specific screenshots.
• DOM Interaction: Click elements, type text, and query elements.
• Inspection: Get DOM tree, element info, and page info.
• JavaScript: Execute arbitrary JavaScript in page context.
• Metro Bundler: Quick shortcuts for React Native development.

📦 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).

💻 Usage Examples

Basic Usage

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

📚 Documentation

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)

Browser Automation Tools (14)

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/plaintest-mcp.git
cd plaintest-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Watch mode
npm run dev

🔧 Technical Details

The @plaintest/mcp-connect server combines the capabilities of xcrun simctl, fb-idb, and Puppeteer. It auto - detects available tools based on the system environment, which helps in reducing unnecessary context usage. The server also provides a unified interface for AI assistants to interact with iOS Simulators and browsers, enabling seamless automation.

📄 License

This project is under the MIT License. See LICENSE for details.

Author

George Al - Haddad - Plaintest