iOS Automation MCP Server

# Mobile automation iOS MCP server > Modern iOS automation server built with FastMCP 2.0 and clean architecture [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://www.apple.com/macos/) [](https://github.com/jlowin/fastmcp) [](#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 [](https://youtu.be/fVqE7nLfqoE) **🎬 Watch the Complete Demo**: [Mobile automation iOS MCP server in Action](https://youtu.be/fVqE7nLfqoE) ## ✨ 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: ```json { "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](https://docs.astral.sh/uv/) (recommended) or pip - Xcode with iOS Simulator - Node.js (for Appium) 2. **Installation** ```bash 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** ```json { "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 | Aspect | Before Refactoring | After Refactoring | |--------|-------------------|-------------------| | **Structure** | Mixed iOS/shared code | Clean platform segregation | | **Maintainability** | Monolithic | Modular & self-contained | | **Extensibility** | iOS-only | Cross-platform ready | | **Code Reuse** | Duplication likely | Shared utilities for all platforms | | **Configuration** | Single settings file | Modular config hierarchy | | **Organization** | Flat structure | Professional enterprise structure | ## 🔧 Available Tools ### `take_screenshot` Capture iOS simulator screenshots ```json { "filename": "optional_name.png", "device_id": "booted" } ``` ### `launch_app` Launch iOS applications ```json { "bundle_id": "com.apple.mobilesafari", "device_id": "booted" } ``` ### `find_and_tap` Find and tap UI elements with smart automation ```json { "accessibility_id": "submitButton", "take_screenshot": true, "dismiss_after_screenshot": false } ``` ### `appium_tap_and_type` Enhanced text input with element finding ```json { "text": "Hello World!", "element_type": "textField", "timeout": 10 } ``` ### `list_simulators` List available iOS simulators ```json {} ``` ### `get_server_status` Check server and Appium status ```json {} ``` ## 🛠️ Development ### Local Development Commands ```bash # 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 ```bash # Install Appium npm install -g appium appium driver install xcuitest # Start Appium server appium server --port 4723 ``` ### Architecture Development ```bash # 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 | Feature | Traditional MCP | FastMCP 2.0 + Clean Architecture | |---------|----------------|----------------------------------| | **Setup** | Complex configuration | Simple Python decorators | | **Architecture** | Monolithic | Modular platform segregation | | **Code Reuse** | Manual duplication | Shared utilities package | | **Type Safety** | Manual validation | Built-in Pydantic models | | **Error Handling** | Basic try-catch | Rich context and logging | | **Deployment** | Local only | Cloud-ready with Railway | | **Extensibility** | Hard to extend | Easy platform addition | | **Maintainability** | Complex | Clean separation of concerns | ## 🔍 Troubleshooting ### Simulator Issues ```bash # List available simulators xcrun simctl list devices # Boot a simulator xcrun simctl boot "iPhone 16 Pro" ``` ### Appium Connection ```bash # 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: ```bash # 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: ```bash # 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 [LICENSE](LICENSE) file for details.