-
security-
license-
qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
19
Works with Apple's development ecosystem, particularly iOS simulators and Xcode tools, to automate testing and development workflows for Apple platforms.
Can be integrated into GitHub Actions CI/CD pipelines for automated iOS testing, allowing for AI-driven test execution in continuous integration workflows.
Enables automation of iOS simulators, performing accessibility testing, managing apps, and executing complex workflows. Provides tools for simulator management, app installation/launching, UI interaction, and screen capture.
Leverages macOS system capabilities for UI automation through AppleScript, accessibility permissions management, and screenshot storage.
Integrates with Xcode's iOS Simulator functionality, allowing for programmatic control of simulators, app installation, and testing features through the simctl commands.
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/packageiOS-specific code contained in
platforms/ios/packageClean 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
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.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables AI assistants to interact with iOS simulators, perform accessibility testing, manage apps, and automate complex iOS workflows.
Related MCP Servers
- Asecurity-licenseAqualityA Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.Last updated -181747
Appwrite MCP Serverofficial
Asecurity-licenseAqualityA Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.Last updated -54MIT License- -security-license-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -361