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
- Claude Desktop Configuration
🏗️ 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
🎯 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
- Shared utilities go in
- 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 -14Python
- 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 -183542TypeScript
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 -8448PythonMIT 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 -31TypeScript