iHackSubhodip/mobile-automation-mcp-server

Mobile automation iOS MCP server

Modern iOS automation server built with FastMCP 2.0 and clean architecture

A production-ready iOS automation MCP server built with FastMCP 2.0, featuring clean modular architecture with complete platform segregation. Ready for cross-platform expansion with iOS-specific and shared components properly separated.

📺 Demo Video

🎬 Watch the Complete Demo: Mobile automation iOS MCP server in Action

✨ Features

• 🚀 FastMCP 2.0 - Modern Python-first MCP implementation
• 🌐 Cloud Deployment - Ready for Railway, Heroku, or other platforms
• 📱 Real iOS Automation - Appium + WebDriverAgent integration
• 🏗️ Clean Modular Architecture - Complete platform segregation & SOLID principles
• 🔄 Cross-Platform Ready - Shared utilities for future Android/other platforms
• 🎨 Beautiful Logging - Colored console output with emojis
• 🔧 Type-Safe - Comprehensive type hints throughout
• 🔌 Extensible - Plugin-style tool system with modular configuration
• 📦 Zero Code Duplication - DRY principles with shared utilities

🚀 Quick Start

Option 1: Remote Server (Recommended)

Use the hosted version on Railway - no local setup required:

{
  "mcpServers": {
    "ios-automation-railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-demo-production.up.railway.app/sse/"
      ]
    }
  }
}

Option 2: Local Development

1. Prerequisites

   • macOS (required for iOS automation)
   • Python 3.11+
   • uv (recommended) or pip
   • Xcode with iOS Simulator
   • Node.js (for Appium)

2. Installation

   git clone https://github.com/iHackSubhodip/mcp-server-demo.git
   cd mcp-server-demo
   
   # Using uv (recommended)
   uv sync
   
   # Or using pip (legacy)
   pip install -e .
   

3. Claude Desktop Configuration

   {
     "mcpServers": {
       "ios-automation-local": {
         "command": "uv",
         "args": ["run", "python", "mobile-automation-mcp-server/fastmcp_server.py"],
         "cwd": "/path/to/mcp-server-demo"
       }
     }
   }
   

🏗️ Architecture

The Mobile automation iOS MCP server features a clean, modular architecture with complete platform segregation achieved through a comprehensive 6-phase refactoring. This design enables maximum maintainability, zero code duplication, and seamless cross-platform expansion.

✨ Architecture Achievements

🎯 Complete Platform Segregation

• Cross-platform utilities isolated in shared/ package
• iOS-specific code contained in platforms/ios/ package
• Clean separation of concerns across all components
• Future-ready for Android in platforms/android/

🔄 DRY Principles Applied

• Shared utilities: Logger, exceptions, command runner
• Base configuration: AppiumConfig, ServerConfig for reuse
• Platform configs: iOS-specific settings separate
• Zero duplication between current/future platforms

🛡️ Maintainable & Extensible

• Self-contained platforms: Each platform completely independent
• Unified interface: Single configuration entry point
• Backward compatible: All existing interfaces preserved
• Professional structure: Enterprise-grade organization

Directory Structure

mobile-automation-mcp-server/
├── fastmcp_server.py          # 🚀 FastMCP 2.0 server (main entry)
├── config/
│   └── settings.py           # 🔧 Unified configuration interface
├── shared/                   # 🌐 Cross-platform utilities & config
│   ├── utils/               # 🛠️ Platform-agnostic utilities  
│   │   ├── logger.py       # 📝 Colored logging with emojis
│   │   ├── exceptions.py   # ⚠️ Exception hierarchy
│   │   └── command_runner.py # 💻 Shell command execution
│   └── config/             # ⚙️ Base configuration classes
│       └── base_settings.py # 📋 AppiumConfig, ServerConfig
├── platforms/ios/          # 🍎 iOS-specific platform code
│   ├── automation/         # 🤖 iOS automation services
│   │   ├── appium_client.py # 📱 iOS automation client
│   │   ├── screenshot_service.py # 📸 Screenshot handling
│   │   └── simulator_manager.py # 🎮 Simulator management
│   ├── tools/             # 🔨 iOS-specific MCP tools
│   │   ├── appium_tap_type_tool.py # ⌨️ Text field automation
│   │   ├── find_and_tap_tool.py    # 👆 Advanced element finding
│   │   ├── launch_app_tool.py      # 🚀 App launching
│   │   └── screenshot_tool.py      # 📷 Screenshot capture
│   └── config/            # ⚙️ iOS-specific configuration
│       └── ios_settings.py # 🍎 iOSConfig (XCUITest, iPhone)
├── screenshots/             # 📁 Screenshot storage
├── Dockerfile              # 🐳 Container deployment
├── Procfile                # 🚂 Railway deployment
└── pyproject.toml          # 📦 Dependencies & project config

🎯 Benefits Achieved

🔧 Available Tools

take_screenshot

Capture iOS simulator screenshots

{
  "filename": "optional_name.png",
  "device_id": "booted"
}

launch_app

Launch iOS applications

{
  "bundle_id": "com.apple.mobilesafari",
  "device_id": "booted"
}

find_and_tap

Find and tap UI elements with smart automation

{
  "accessibility_id": "submitButton",
  "take_screenshot": true,
  "dismiss_after_screenshot": false
}

appium_tap_and_type

Enhanced text input with element finding

{
  "text": "Hello World!",
  "element_type": "textField",
  "timeout": 10
}

list_simulators

List available iOS simulators

{}

get_server_status

Check server and Appium status

{}

🛠️ Development

Local Development Commands

# Run FastMCP server locally (with uv)
uv run python mobile-automation-mcp-server/fastmcp_server.py

# Install dependencies (if needed)
uv sync

# Development mode (with dev dependencies)
uv sync --dev

Appium Setup

# Install Appium
npm install -g appium
appium driver install xcuitest

# Start Appium server
appium server --port 4723

Architecture Development

# The modular structure makes development easier:

# Work on shared utilities (affects all platforms)
cd shared/utils/

# Work on iOS-specific features  
cd platforms/ios/

# Work on configuration
cd config/

# Add new platforms (future)
mkdir platforms/android/

🌐 Cloud Deployment

This server is deployed on Railway and accessible via:

• HTTP Endpoint: https://mcp-server-demo-production.up.railway.app/
• SSE Endpoint: https://mcp-server-demo-production.up.railway.app/sse/

The cloud deployment simulates iOS automation responses for demonstration purposes.

📊 Key Improvements

🔍 Troubleshooting

Simulator Issues

# List available simulators
xcrun simctl list devices

# Boot a simulator
xcrun simctl boot "iPhone 16 Pro"

Appium Connection

# Check Appium status
curl http://localhost:4723/status

# Restart Appium
pkill -f appium && appium server --port 4723

📝 Dependencies

Core dependencies managed via pyproject.toml:

• fastmcp>=2.9.2 - FastMCP 2.0 framework
• mcp>=1.0.0 - Traditional MCP protocol
• aiohttp>=3.9.0 - HTTP client for automation
• appium-python-client>=3.0.0 - iOS automation
• pydantic>=2.4.0 - Data validation

Install with:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the clean architecture patterns:
   • Shared utilities go in shared/
   • Platform-specific code goes in platforms/{platform}/
   • Configuration follows the modular hierarchy
4. Add comprehensive error handling
5. Submit a pull request

🚀 Future Expansion

Thanks to the clean architecture, adding new platforms is straightforward:

# Add Android platform (example)
mkdir -p platforms/android/{automation,tools,config}

# Reuse shared utilities
from shared.utils import get_logger, AutomationMCPError
from shared.config import AppiumConfig, ServerConfig

# Create Android-specific config
from platforms.android.config import AndroidConfig

📄 License

This project is licensed under the MIT License - see the file for details.