# @plaintest/mcp-connect
[](https://www.npmjs.com/package/@plaintest/mcp-connect)
[](https://www.npmjs.com/package/@plaintest/mcp-connect)
[](https://www.npmjs.com/package/@plaintest/mcp-connect)
[](https://opensource.org/licenses/MIT)
[](https://github.com/plaintest/mcp-connect)
[](https://github.com/plaintest/mcp-connect/issues)
[](https://nodejs.org)
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:
```bash
# 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:
```bash
npm install -g @plaintest/mcp-connect
```
Then configure your MCP client manually:
```json
{
"mcpServers": {
"mcp-connect": {
"command": "mcp-connect"
}
}
}
```
### Option 3: Manual Configuration
If you prefer not to install globally, configure your MCP client to use npx:
```json
{
"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
```bash
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:
```bash
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:
```json
{
"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:
```bash
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
```bash
# 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
```bash
# 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](LICENSE) for details.
## Author
George Al-Haddad - [Plaintest](https://github.com/plaintest)
