Which integrations are available for this server?

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.

How do I use iOS Automation MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iOS Automation MCP Server take a screenshot of the current simulator screen" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Mobile automation iOS MCP server

Modern iOS automation server built with FastMCP 2.0 and clean architecture

License: MIT Python 3.11+ Platform: macOS FastMCP 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

🎬 Watch the Complete Demo: Mobile automation iOS MCP server in Action

Related MCP server: Xcode MCP Server

✨ 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 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:

# 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.

iOS Automation MCP Server