Skip to main content
Glama

iOS Automation MCP Server

README.md•10.5 kB
# Mobile automation iOS MCP server > Modern iOS automation server built with FastMCP 2.0 and clean architecture [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/) [![FastMCP](https://img.shields.io/badge/FastMCP-2.0-green.svg)](https://github.com/jlowin/fastmcp) [![Architecture](https://img.shields.io/badge/Architecture-Clean%20%26%20Modular-brightgreen.svg)](#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 [![Mobile automation iOS MCP server Demo](https://img.youtube.com/vi/480AmvL9ziQ/maxresdefault.jpg)](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.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/iHackSubhodip/mcp-server-demo'

If you have feedback or need assistance with the MCP directory API, please join our Discord server