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:
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
šÆ 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
launch_app
Launch iOS applications
find_and_tap
Find and tap UI elements with smart automation
appium_tap_and_type
Enhanced text input with element finding
list_simulators
List available iOS simulators
get_server_status
Check server and Appium status
š ļø Development
Local Development Commands
Appium Setup
Architecture Development
š 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
Appium Connection
š 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:
š¤ 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:
š 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
- -securityFlicense-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
- AsecurityFlicenseAqualityA 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
AsecurityAlicenseAqualityA 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- -securityFlicense-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