Skip to main content
Glama

iOS Automation MCP Server

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

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

  1. Prerequisites
    • macOS (required for iOS automation)
    • Python 3.11+
    • uv (recommended) or pip
    • Xcode with iOS Simulator
    • Node.js (for Appium)
  2. 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 .
  3. 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

AspectBefore RefactoringAfter Refactoring
StructureMixed iOS/shared codeClean platform segregation
MaintainabilityMonolithicModular & self-contained
ExtensibilityiOS-onlyCross-platform ready
Code ReuseDuplication likelyShared utilities for all platforms
ConfigurationSingle settings fileModular config hierarchy
OrganizationFlat structureProfessional 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

FeatureTraditional MCPFastMCP 2.0 + Clean Architecture
SetupComplex configurationSimple Python decorators
ArchitectureMonolithicModular platform segregation
Code ReuseManual duplicationShared utilities package
Type SafetyManual validationBuilt-in Pydantic models
Error HandlingBasic try-catchRich context and logging
DeploymentLocal onlyCloud-ready with Railway
ExtensibilityHard to extendEasy platform addition
MaintainabilityComplexClean 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

  1. Fork the repository
  2. Create a feature branch
  3. Follow the clean architecture patterns:
    • Shared utilities go in shared/
    • Platform-specific code goes in platforms/{platform}/
    • Configuration follows the modular hierarchy
  4. Add comprehensive error handling
  5. 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.

Related MCP Servers

  • -
    security
    F
    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 -
    14
    Python
    • Apple
    • Linux
  • A
    security
    F
    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
    35
    42
    TypeScript
  • A
    security
    A
    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 -
    84
    48
    Python
    MIT License
    • Linux
    • Apple
  • -
    security
    F
    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 -
    3
    1
    TypeScript

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/iHackSubhodip/mcp-server-demo'

If you have feedback or need assistance with the MCP directory API, please join our Discord server