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

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

This server cannot be installed

security - not tested

license - not tested

quality - not tested

How are these scores calculated?

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

MCP Personal Assistant Agent
zhangzhongnan928
-
security
-
license
-
quality
A 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
Xcode MCP Server
PolarVista
A
security
-
license
A
quality
A 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 -
18
17
47
Appwrite MCP Serverofficial
appwrite
A
security
-
license
A
quality
A 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 -
54
MIT License
MCP Toolkit
zxfgds
-
security
-
license
-
quality
A 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 -
36
1

View all related MCP servers

iOS Automation MCP Server