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
-
Prerequisites
- macOS (required for iOS automation)
- Python 3.11+
- uv (recommended) or pip
- Xcode with iOS Simulator
- Node.js (for Appium)
-
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 . -
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
| 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
{
"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
| 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
# 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 frameworkmcp>=1.0.0- Traditional MCP protocolaiohttp>=3.9.0- HTTP client for automationappium-python-client>=3.0.0- iOS automationpydantic>=2.4.0- Data validation
Install with:
# Using uv (recommended)
uv sync
# Or using pip
pip install -e .
🤝 Contributing
- Fork the repository
- Create a feature branch
- Follow the clean architecture patterns:
- Shared utilities go in
shared/ - Platform-specific code goes in
platforms/{platform}/ - Configuration follows the modular hierarchy
- Shared utilities go in
- Add comprehensive error handling
- 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 LICENSE file for details.