iOS Automation MCP Server

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, offering both local and cloud deployment options. Features clean architecture, comprehensive error handling, and professional logging.

📺 Demo Video

🎬 Watch the Complete Demo: 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 Architecture - SOLID principles and design patterns
🎨 Beautiful Logging - Colored console output with emojis
🔧 Type-Safe - Comprehensive type hints throughout
🔌 Extensible - Plugin-style tool system

🚀 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+
- Xcode with iOS Simulator
- Node.js (for Appium)
Installation
git clone https://github.com/iHackSubhodip/mcp-server-demo.git cd mcp-server-demo pip install -r ios_mcp_server/requirements.txt
Claude Desktop Configuration
{ "mcpServers": { "ios-automation-local": { "command": "python", "args": ["-m", "ios_mcp_server.main"], "cwd": "/path/to/mcp-server-demo" } } }

🏗️ Architecture

Directory Structure

ios_mcp_server/
├── main.py                     # Entry point
├── fastmcp_server.py          # FastMCP 2.0 server
├── config/
│   └── settings.py           # Configuration management
├── automation/               # Core automation services
│   ├── appium_client.py     # iOS automation client
│   ├── screenshot_service.py # Screenshot handling
│   └── simulator_manager.py # Simulator management
├── tools/                   # MCP tools
│   ├── base_tool.py        # Abstract base class
│   ├── tool_registry.py    # Tool management
│   ├── appium_tap_type_tool.py
│   ├── find_and_tap_tool.py
│   ├── launch_app_tool.py
│   └── screenshot_tool.py
├── utils/                   # Shared utilities
│   ├── logger.py           # Colored logging
│   ├── exceptions.py       # Custom exceptions
│   └── command_runner.py   # Async command execution
├── server/                  # Traditional MCP server
├── screenshots/             # Screenshot storage
├── Dockerfile              # Container deployment
├── Procfile                # Railway deployment
└── requirements.txt        # Dependencies

🔧 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 FastMCP Development

# Install dependencies
pip install -r ios_mcp_server/requirements.txt

# Run FastMCP server
python ios_mcp_server/fastmcp_server.py

Traditional MCP Development

# Run traditional MCP server
python -m ios_mcp_server.main

Appium Setup

# Install Appium
npm install -g appium
appium driver install xcuitest

# Start Appium server
appium server --port 4723

🌐 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
Setup	Complex configuration	Simple Python decorators
Type Safety	Manual validation	Built-in Pydantic models
Error Handling	Basic try-catch	Rich context and logging
Deployment	Local only	Cloud-ready with Railway
Development	Boilerplate heavy	Clean, intuitive API

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

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

🤝 Contributing

Fork the repository
Create a feature branch
Follow the existing architecture patterns
Add comprehensive error handling
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

This server cannot be installed

security - not tested

license - permissive license

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
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 -
2
Python
Xcode MCP Server
PolarVista
-
security
F
license
-
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 -
29
TypeScript
Appwrite MCP Serverofficial
appwrite
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
40
Python
MIT License
MCP Toolkit
zxfgds
-
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 -
16
TypeScript

View all related MCP servers

Appeared in Searches

Tools and Methods for Testing the UI of Electron Apps