iHackSubhodip/mcp-server-demo

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

1. Prerequisites

   • macOS (required for iOS automation)
   • Python 3.11+
   • Xcode with iOS Simulator
   • Node.js (for Appium)

2. Installation

   git clone https://github.com/iHackSubhodip/mcp-server-demo.git
   cd mcp-server-demo
   pip install -r ios_mcp_server/requirements.txt
   

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

🔍 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

1. Fork the repository
2. Create a feature branch
3. Follow the existing architecture patterns
4. Add comprehensive error handling
5. Submit a pull request

📄 License

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