Recursive MCP

MCP server for automated iOS app testing via natural language instructions.

Overview

Recursive MCP is a Model Context Protocol server that enables AI agents to test iOS applications through natural language commands. It provides iOS automation tools for Claude Code, which handles the AI aspects without requiring API keys.

New in v2.3.0 🚀

• Dynamic App Building: Automatically builds, installs, and launches any iOS app
• Auto Bundle ID Detection: No need to specify bundle IDs manually
• Smart Simulator Management: Auto-detects available devices with helpful fallbacks
• Live Testing Mode: Test apps interactively with natural language commands
• Production-Ready Error Handling: Detailed troubleshooting for common issues
• Zero Configuration: Works out of the box with any iOS project

Features

• Natural language test instructions
• Automatic code analysis and debug placement suggestions
• iOS Simulator automation
• Comprehensive test reporting
• Debug statement tracking with [RECURSIVE_DEBUG] prefix
• No Claude Code CLI required - works directly with MCP clients
• 5-phase recursive testing system

Installation

Quick Install (Recommended)

# One-line install with automatic configuration
curl -fsSL https://raw.githubusercontent.com/hpottipati/Recursion-mobile/main/recursive-mcp/install.sh | bash

This will:

• Configure npm to use GitHub Packages
• Install the MCP server
• Set up your MCP configuration automatically
• Set up the MCP configuration

Manual Installation

If you prefer to install manually:

# 1. Configure npm for GitHub Packages
echo "@christian1011:registry=https://npm.pkg.github.com" >> ~/.npmrc

# 2. Install the package
npm install -g @christian1011/recursive-mcp --registry=https://npm.pkg.github.com

# 3. Update your MCP configuration (see Configuration section below)

Configuration

No API Keys Required

Recursive MCP works directly with Claude Code - no API keys needed! Claude Code handles all AI processing using your logged-in account.

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

Simple Configuration

The MCP server is now simplified and doesn't require model configuration. Claude Code handles all AI processing using your account.

Available Tools

test_ios_feature

Test iOS app features using natural language instructions.

Parameters:

• instruction (string, required): Natural language test instruction
• app_path (string, required): Path to .xcodeproj or .xcworkspace
• debug_points (array, optional): Specific files to add debug statements

analyze_test_results

Analyze console output from test execution.

Parameters:

• console_output (string, required): Console output from test execution
• expected_behavior (string, optional): Expected behavior description

recursive_configure

Update Recursive MCP configuration at runtime.

Parameters:

• setting (string, required): Configuration path (e.g., 'simulator.device')
• value (string/number/boolean, required): New value for the setting

start_live_test (NEW!)

Start an interactive live test session that builds and launches your app.

Parameters:

• app_path (string, required): Path to .xcodeproj or .xcworkspace
• bundle_id (string, optional): Bundle ID (auto-detected if not provided)
• attach_to_running (boolean, optional): Attach to already running app (default: true)

send_live_command (NEW!)

Send commands to the running live test session.

Parameters:

• instruction (string, optional): Natural language command (e.g., "tap the login button")
• action (string, optional): Direct action (tap, type, swipe, get_tree)
• target (string, optional): Target element for the action
• value (string, optional): Value for the action

get_live_state

Get the current UI accessibility tree from the live test.

stop_live_test

Stop the running live test session.

Requirements

• macOS
• Xcode 15+
• Node.js 18+
• iOS Simulator

Usage Examples

Basic Test

// Test login functionality
await use_mcp_tool({
  server_name: "recursive-mcp",
  tool_name: "test_ios_feature",
  arguments: {
    instruction: "Test login with valid credentials",
    app_path: "/path/to/YourApp.xcodeproj"
  }
});

Live Interactive Testing (NEW!)

// Start a live test session
await use_mcp_tool({
  server_name: "recursive-mcp",
  tool_name: "start_live_test",
  arguments: {
    app_path: "/path/to/YourApp.xcodeproj",
    attach_to_running: false  // Build and launch fresh
  }
});

// Send natural language commands
await use_mcp_tool({
  server_name: "recursive-mcp",
  tool_name: "send_live_command",
  arguments: {
    instruction: "tap the login button and enter [email protected]"
  }
});

// Or use direct actions
await use_mcp_tool({
  server_name: "recursive-mcp",
  tool_name: "send_live_command",
  arguments: {
    action: "tap",
    target: "Login"
  }
});

Configuration

// Change simulator device
await use_mcp_tool({
  server_name: "recursive-mcp",
  tool_name: "recursive_configure",
  arguments: {
    setting: "simulator.device",
    value: "iPhone 15 Pro"
  }
});

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│   MCP Protocol  │────▶│  Recursive MCP  │
│  (logged in)    │     │   (no API key)  │     │     Server      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                                │
         │◀───────────────────────────────────────────────┘
         │              (iOS automation tools)
         │
         └─> Uses built-in AI capabilities

1. Claude Code uses your logged-in account for AI processing
2. Recursive MCP provides iOS automation tools
3. No API keys are passed or stored
4. Results are returned through the MCP protocol

Troubleshooting

Connection Issues

If the MCP fails to connect:

1. Ensure you're using the correct package name: @christiankyun/recursive-mcp
2. Restart Claude Code after configuration changes
3. Check that Xcode is installed and accessible

Test Execution Issues

If tests aren't running properly:

1. Verify your project path is correct
2. Ensure the iOS Simulator is available
3. Check that your project builds successfully in Xcode

Security & Privacy

• No API keys required or stored
• All AI processing happens in Claude Code
• Test results and debug data stay on your local machine
• No telemetry or usage tracking

License

PROPRIETARY - This software is proprietary and confidential. See LICENSE file for details.

Support

For licensing inquiries: [email protected]