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

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

  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

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

  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 -
    19
    • 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
    17
    47
  • 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 -
    54
    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 -
    36
    1

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