recursive-mcp

MCP server for iOS UI automation testing using XCUITest and natural language commands

Overview

recursive-mcp is a Model Context Protocol (MCP) server that enables AI agents to control iOS simulators through natural language commands. It bridges AI assistants like Claude with iOS XCUITest automation, allowing for intelligent app testing and interaction.

Architecture

AI Agent (Claude, Cursor, etc.)
    ↓ MCP Protocol
MCP Server (Node.js)
    ↓ TCP (port 12345)
iOS Test Runner (Swift/XCUITest)
    ↓ Accessibility APIs
iOS Simulator

Features

• 🚀 Natural language iOS control - Control iOS apps using plain English
• 🤖 MCP integration - Works with Claude Desktop, Cursor, VS Code, and more
• 📱 XCUITest automation - Uses Apple's official testing framework
• 🔧 Zero configuration - Works out of the box
• 📸 Screenshot support - Capture and analyze UI states
• 🔍 Element inspection - Get information about UI elements
• ⚡ Real-time feedback - See console output and debug information

Quick Start

# Install and set up Recursive MCP
npx recursive-mcp@latest init

# Or with options
npx recursive-mcp@latest init --directory ./my-mcp-project --verbose

System Requirements

• macOS (required for Xcode and iOS development)
• Node.js 18+ (for MCP server)
• Xcode 15+ (for building iOS test runner)
• Command Line Tools (for development tools)

Installation

Basic Installation

npx recursive-mcp@latest init

Advanced Options

npx recursive-mcp@latest init \
  --directory ./my-project \
  --verbose \
  --no-build

Command Reference

init

Main installation command that sets up the complete Recursive MCP environment.

Options:

• -d, --directory <path> - Installation directory (default: current directory)
• --skip-checks - Skip prerequisite checks (not recommended)
• --no-build - Skip building iOS test runner
• --verbose - Enable verbose logging
• --dry-run - Show what would be done without executing

check

Check system prerequisites without installing.

npx recursive-mcp@latest check

Options:

• --verbose - Enable verbose logging

What Gets Installed

The installer sets up the following components:

1. MCP Server

   • Node.js server implementing MCP protocol
   • TCP client for iOS communication
   • Command translator for natural language processing

2. iOS Test Runner

   • Swift XCUITest runner
   • TCP server listening on port 12345
   • Accessibility-based UI automation

3. Configuration Files

   • Client-specific MCP configurations
   • Environment templates
   • Setup documentation for each client

Directory Structure

After installation:

my-project/
├── mcp-server/              # MCP server implementation
│   ├── src/                 # TypeScript source
│   ├── dist/                # Compiled JavaScript
│   └── package.json
├── ios-test-runner/         # iOS XCUITest runner
│   ├── TestListener.swift   # TCP server
│   ├── TestExecutor.swift   # Command execution
│   ├── Package.swift        # Swift package
│   └── README.md
└── mcp-config/              # MCP client configurations
    ├── claude-desktop/
    ├── cursor/
    ├── vs-code/
    ├── continue/
    └── generic/

MCP Tools Available

Once installed, these tools are available through MCP:

• tap - Tap on UI elements by description
• type_text - Enter text in the current field
• swipe - Perform swipe gestures
• scroll - Scroll the screen
• launch_app - Launch apps by name
• press_button - Press system buttons (home, back)
• take_screenshot - Capture current screen
• wait - Wait for specified duration
• verify_element - Check if element exists
• get_screen_info - Get information about current screen

Usage Examples

After installation:

1. Start the iOS Test Runner:

   cd ios-test-runner
   ./build.sh
   # This starts the test runner and TCP server

2. Start the MCP server:

   cd mcp-server
   npm run start

3. Configure your MCP client using the generated configuration files

4. Use natural language commands:

   • "Launch the Settings app"
   • "Tap on General"
   • "Type 'test@example.com' in the email field"
   • "Take a screenshot"
   • "Swipe up to scroll"

Client Configuration

Claude Desktop

# Configuration location
~/Library/Application Support/Claude/mcp.json

Cursor

# Project-specific configuration
.cursor/mcp.json

VS Code

# Add to settings.json
{
  "mcp.servers": {
    "recursive-mcp": { ... }
  }
}

Troubleshooting

Common Issues

Prerequisites check failed:

# Check what's missing
npx recursive-mcp@latest check --verbose

# Install Xcode Command Line Tools
xcode-select --install

iOS Test Runner build failed:

# Check Xcode installation
xcodebuild -version
xcode-select -p

# Clean and rebuild
cd ios-test-runner
xcodebuild clean
./build.sh

MCP server won't start:

# Check Node.js version
node --version  # Should be 18+

# Install dependencies
cd mcp-server
npm install
npm run build

TCP connection issues:

# Check if test runner is listening
lsof -i :12345

# Restart both components
# Terminal 1: iOS Test Runner
cd ios-test-runner && ./build.sh

# Terminal 2: MCP Server
cd mcp-server && npm run start

Debug Mode

Enable verbose logging:

# Installation
npx recursive-mcp@latest init --verbose

# MCP Server
DEBUG=* npm run start

# iOS Test Runner
# Check console output in Xcode

Development

Building from Source

# Clone this repository
git clone https://github.com/recursive-mcp/recursive-mcp.git
cd recursive-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
npm run cli init

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

How It Works

1. Natural Language Input: AI agents send commands like "tap on the login button"
2. MCP Server: Receives commands via MCP protocol and translates them
3. TCP Communication: Sends structured commands to iOS test runner on port 12345
4. XCUITest Execution: Test runner uses Apple's accessibility APIs to perform actions
5. Feedback Loop: Screenshots and console output are sent back to the AI agent

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation: Check the generated configuration files and setup guides
• 🐛 Issues: Report bugs on GitHub Issues
• 💬 Discussions: Join the community discussions

Related Projects

• MCP SDK - Model Context Protocol SDK
• Claude Desktop - AI assistant with MCP support
• Cursor - AI-powered IDE with MCP integration
• PhoneAgent - Inspiration for iOS automation approach

Ready to automate your iOS app testing with AI? Get started with recursive-mcp today!