{"id":30232194,"url":"https://github.com/ihacksubhodip/mobile-automation-mcp-server","last_synced_at":"2025-08-14T23:38:44.428Z","repository":{"id":301069441,"uuid":"1008047183","full_name":"iHackSubhodip/mobile-automation-mcp-server","owner":"iHackSubhodip","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-26T12:41:42.000Z","size":46094,"stargazers_count":12,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-26T18:35:50.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://mcp-server-demo-production.up.railway.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iHackSubhodip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T00:19:08.000Z","updated_at":"2025-07-26T12:41:46.000Z","dependencies_parsed_at":"2025-07-26T18:35:53.562Z","dependency_job_id":null,"html_url":"https://github.com/iHackSubhodip/mobile-automation-mcp-server","commit_stats":null,"previous_names":["ihacksubhodip/mcp-server-demo","ihacksubhodip/mobile-automation-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iHackSubhodip/mobile-automation-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmobile-automation-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmobile-automation-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmobile-automation-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmobile-automation-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iHackSubhodip","download_url":"https://codeload.github.com/iHackSubhodip/mobile-automation-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmobile-automation-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270500363,"owners_count":24595156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-14T23:38:41.133Z","updated_at":"2025-08-14T23:38:44.423Z","avatar_url":"https://github.com/iHackSubhodip.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mobile automation iOS MCP server\n\n\u003e Modern iOS automation server built with FastMCP 2.0 and clean architecture\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)\n[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-green.svg)](https://github.com/jlowin/fastmcp)\n[![Architecture](https://img.shields.io/badge/Architecture-Clean%20%26%20Modular-brightgreen.svg)](#architecture)\n\nA 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.\n\n## 📺 Demo Video\n\n[![Mobile automation iOS MCP server Demo](https://img.youtube.com/vi/480AmvL9ziQ/maxresdefault.jpg)](https://youtu.be/fVqE7nLfqoE)\n\n**🎬 Watch the Complete Demo**: [Mobile automation iOS MCP server in Action](https://youtu.be/fVqE7nLfqoE)\n\n## ✨ Features\n\n- 🚀 **FastMCP 2.0** - Modern Python-first MCP implementation\n- 🌐 **Cloud Deployment** - Ready for Railway, Heroku, or other platforms\n- 📱 **Real iOS Automation** - Appium + WebDriverAgent integration\n- 🏗️ **Clean Modular Architecture** - Complete platform segregation \u0026 SOLID principles\n- 🔄 **Cross-Platform Ready** - Shared utilities for future Android/other platforms\n- 🎨 **Beautiful Logging** - Colored console output with emojis\n- 🔧 **Type-Safe** - Comprehensive type hints throughout\n- 🔌 **Extensible** - Plugin-style tool system with modular configuration\n- 📦 **Zero Code Duplication** - DRY principles with shared utilities\n\n## 🚀 Quick Start\n\n### Option 1: Remote Server (Recommended)\n\nUse the hosted version on Railway - no local setup required:\n\n```json\n{\n  \"mcpServers\": {\n    \"ios-automation-railway\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://mcp-server-demo-production.up.railway.app/sse/\"\n      ]\n    }\n  }\n}\n```\n\n### Option 2: Local Development\n\n1. **Prerequisites**\n   - macOS (required for iOS automation)\n   - Python 3.11+\n   - [uv](https://docs.astral.sh/uv/) (recommended) or pip\n   - Xcode with iOS Simulator\n   - Node.js (for Appium)\n\n2. **Installation**\n   ```bash\n   git clone https://github.com/iHackSubhodip/mcp-server-demo.git\n   cd mcp-server-demo\n   \n   # Using uv (recommended)\n   uv sync\n   \n   # Or using pip (legacy)\n   pip install -e .\n   ```\n\n3. **Claude Desktop Configuration**\n   ```json\n   {\n     \"mcpServers\": {\n       \"ios-automation-local\": {\n         \"command\": \"uv\",\n         \"args\": [\"run\", \"python\", \"mobile-automation-mcp-server/fastmcp_server.py\"],\n         \"cwd\": \"/path/to/mcp-server-demo\"\n       }\n     }\n   }\n   ```\n\n## 🏗️ Architecture\n\nThe 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.\n\n### ✨ Architecture Achievements\n\n**🎯 Complete Platform Segregation**\n- **Cross-platform utilities** isolated in `shared/` package\n- **iOS-specific code** contained in `platforms/ios/` package  \n- **Clean separation** of concerns across all components\n- **Future-ready** for Android in `platforms/android/`\n\n**🔄 DRY Principles Applied**\n- **Shared utilities**: Logger, exceptions, command runner\n- **Base configuration**: AppiumConfig, ServerConfig for reuse\n- **Platform configs**: iOS-specific settings separate\n- **Zero duplication** between current/future platforms\n\n**🛡️ Maintainable \u0026 Extensible**\n- **Self-contained platforms**: Each platform completely independent\n- **Unified interface**: Single configuration entry point\n- **Backward compatible**: All existing interfaces preserved\n- **Professional structure**: Enterprise-grade organization\n\n### Directory Structure\n```\nmobile-automation-mcp-server/\n├── fastmcp_server.py          # 🚀 FastMCP 2.0 server (main entry)\n├── config/\n│   └── settings.py           # 🔧 Unified configuration interface\n├── shared/                   # 🌐 Cross-platform utilities \u0026 config\n│   ├── utils/               # 🛠️ Platform-agnostic utilities  \n│   │   ├── logger.py       # 📝 Colored logging with emojis\n│   │   ├── exceptions.py   # ⚠️ Exception hierarchy\n│   │   └── command_runner.py # 💻 Shell command execution\n│   └── config/             # ⚙️ Base configuration classes\n│       └── base_settings.py # 📋 AppiumConfig, ServerConfig\n├── platforms/ios/          # 🍎 iOS-specific platform code\n│   ├── automation/         # 🤖 iOS automation services\n│   │   ├── appium_client.py # 📱 iOS automation client\n│   │   ├── screenshot_service.py # 📸 Screenshot handling\n│   │   └── simulator_manager.py # 🎮 Simulator management\n│   ├── tools/             # 🔨 iOS-specific MCP tools\n│   │   ├── appium_tap_type_tool.py # ⌨️ Text field automation\n│   │   ├── find_and_tap_tool.py    # 👆 Advanced element finding\n│   │   ├── launch_app_tool.py      # 🚀 App launching\n│   │   └── screenshot_tool.py      # 📷 Screenshot capture\n│   └── config/            # ⚙️ iOS-specific configuration\n│       └── ios_settings.py # 🍎 iOSConfig (XCUITest, iPhone)\n├── screenshots/             # 📁 Screenshot storage\n├── Dockerfile              # 🐳 Container deployment\n├── Procfile                # 🚂 Railway deployment\n└── pyproject.toml          # 📦 Dependencies \u0026 project config\n```\n\n### 🎯 Benefits Achieved\n\n| Aspect | Before Refactoring | After Refactoring |\n|--------|-------------------|-------------------|\n| **Structure** | Mixed iOS/shared code | Clean platform segregation |\n| **Maintainability** | Monolithic | Modular \u0026 self-contained |\n| **Extensibility** | iOS-only | Cross-platform ready |\n| **Code Reuse** | Duplication likely | Shared utilities for all platforms |\n| **Configuration** | Single settings file | Modular config hierarchy |\n| **Organization** | Flat structure | Professional enterprise structure |\n\n## 🔧 Available Tools\n\n### `take_screenshot`\nCapture iOS simulator screenshots\n```json\n{\n  \"filename\": \"optional_name.png\",\n  \"device_id\": \"booted\"\n}\n```\n\n### `launch_app`\nLaunch iOS applications\n```json\n{\n  \"bundle_id\": \"com.apple.mobilesafari\",\n  \"device_id\": \"booted\"\n}\n```\n\n### `find_and_tap`\nFind and tap UI elements with smart automation\n```json\n{\n  \"accessibility_id\": \"submitButton\",\n  \"take_screenshot\": true,\n  \"dismiss_after_screenshot\": false\n}\n```\n\n### `appium_tap_and_type`\nEnhanced text input with element finding\n```json\n{\n  \"text\": \"Hello World!\",\n  \"element_type\": \"textField\",\n  \"timeout\": 10\n}\n```\n\n### `list_simulators`\nList available iOS simulators\n```json\n{}\n```\n\n### `get_server_status`\nCheck server and Appium status\n```json\n{}\n```\n\n## 🛠️ Development\n\n### Local Development Commands\n```bash\n# Run FastMCP server locally (with uv)\nuv run python mobile-automation-mcp-server/fastmcp_server.py\n\n# Install dependencies (if needed)\nuv sync\n\n# Development mode (with dev dependencies)\nuv sync --dev\n```\n\n### Appium Setup\n```bash\n# Install Appium\nnpm install -g appium\nappium driver install xcuitest\n\n# Start Appium server\nappium server --port 4723\n```\n\n### Architecture Development\n```bash\n# The modular structure makes development easier:\n\n# Work on shared utilities (affects all platforms)\ncd shared/utils/\n\n# Work on iOS-specific features  \ncd platforms/ios/\n\n# Work on configuration\ncd config/\n\n# Add new platforms (future)\nmkdir platforms/android/\n```\n\n## 🌐 Cloud Deployment\n\nThis server is deployed on Railway and accessible via:\n- **HTTP Endpoint**: `https://mcp-server-demo-production.up.railway.app/`\n- **SSE Endpoint**: `https://mcp-server-demo-production.up.railway.app/sse/`\n\nThe cloud deployment simulates iOS automation responses for demonstration purposes.\n\n## 📊 Key Improvements\n\n| Feature | Traditional MCP | FastMCP 2.0 + Clean Architecture |\n|---------|----------------|----------------------------------|\n| **Setup** | Complex configuration | Simple Python decorators |\n| **Architecture** | Monolithic | Modular platform segregation |\n| **Code Reuse** | Manual duplication | Shared utilities package |\n| **Type Safety** | Manual validation | Built-in Pydantic models |\n| **Error Handling** | Basic try-catch | Rich context and logging |\n| **Deployment** | Local only | Cloud-ready with Railway |\n| **Extensibility** | Hard to extend | Easy platform addition |\n| **Maintainability** | Complex | Clean separation of concerns |\n\n## 🔍 Troubleshooting\n\n### Simulator Issues\n```bash\n# List available simulators\nxcrun simctl list devices\n\n# Boot a simulator\nxcrun simctl boot \"iPhone 16 Pro\"\n```\n\n### Appium Connection\n```bash\n# Check Appium status\ncurl http://localhost:4723/status\n\n# Restart Appium\npkill -f appium \u0026\u0026 appium server --port 4723\n```\n\n## 📝 Dependencies\n\nCore dependencies managed via `pyproject.toml`:\n- `fastmcp\u003e=2.9.2` - FastMCP 2.0 framework\n- `mcp\u003e=1.0.0` - Traditional MCP protocol\n- `aiohttp\u003e=3.9.0` - HTTP client for automation\n- `appium-python-client\u003e=3.0.0` - iOS automation\n- `pydantic\u003e=2.4.0` - Data validation\n\nInstall with:\n```bash\n# Using uv (recommended)\nuv sync\n\n# Or using pip\npip install -e .\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Follow the clean architecture patterns:\n   - **Shared utilities** go in `shared/`\n   - **Platform-specific code** goes in `platforms/{platform}/`\n   - **Configuration** follows the modular hierarchy\n4. Add comprehensive error handling\n5. Submit a pull request\n\n## 🚀 Future Expansion\n\nThanks to the clean architecture, adding new platforms is straightforward:\n\n```bash\n# Add Android platform (example)\nmkdir -p platforms/android/{automation,tools,config}\n\n# Reuse shared utilities\nfrom shared.utils import get_logger, AutomationMCPError\nfrom shared.config import AppiumConfig, ServerConfig\n\n# Create Android-specific config\nfrom platforms.android.config import AndroidConfig\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihacksubhodip%2Fmobile-automation-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fihacksubhodip%2Fmobile-automation-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihacksubhodip%2Fmobile-automation-mcp-server/lists"}