Mobile Automation MCP Server

🚀 移動自動化iOS MCP服務器

這是一個基於FastMCP 2.0構建的現代化iOS自動化服務器，採用了簡潔的架構，解決了iOS自動化測試的複雜性問題，為開發者提供了高效、可擴展的自動化解決方案。

這是一個基於FastMCP 2.0構建的、可用於生產環境的iOS自動化MCP服務器，具有簡潔的模塊化架構，實現了完整的平臺隔離。它將iOS特定組件和共享組件進行了合理分離，為跨平臺擴展做好了準備。

🚀 快速開始

選項1：遠程服務器（推薦）

使用Railway上託管的版本，無需進行本地設置：

{
  "mcpServers": {
    "ios-automation-railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-demo-production.up.railway.app/sse/"
      ]
    }
  }
}

選項2：本地開發

1. 前提條件

   • macOS（iOS自動化必需）
   • Python 3.11+
   • uv（推薦）或pip
   • 安裝了iOS模擬器的Xcode
   • Node.js（用於Appium）

2. 安裝

   git clone https://github.com/iHackSubhodip/mcp-server-demo.git
   cd mcp-server-demo
   
   # 使用uv（推薦）
   uv sync
   
   # 或者使用pip（傳統方式）
   pip install -e .
   

3. Claude桌面配置

   {
     "mcpServers": {
       "ios-automation-local": {
         "command": "uv",
         "args": ["run", "python", "mobile-automation-mcp-server/fastmcp_server.py"],
         "cwd": "/path/to/mcp-server-demo"
       }
     }
   }
   

✨ 主要特性

• 🚀 FastMCP 2.0 - 現代的、以Python為先的MCP實現
• 🌐 雲部署 - 支持Railway、Heroku或其他平臺
• 📱 真實iOS自動化 - 集成了Appium和WebDriverAgent
• 🏗️ 簡潔的模塊化架構 - 實現了完整的平臺隔離，並遵循SOLID原則
• 🔄 跨平臺就緒 - 具備共享工具，為未來的Android或其他平臺做準備
• 🎨 美觀的日誌記錄 - 帶有表情符號的彩色控制檯輸出
• 🔧 類型安全 - 全程使用全面的類型提示
• 🔌 可擴展 - 採用插件式工具系統和模塊化配置
• 📦 零代碼重複 - 遵循DRY原則，使用共享工具

📺 演示視頻

🎬 觀看完整演示：移動自動化iOS MCP服務器實戰

🏗️ 架構

移動自動化iOS MCP服務器具有簡潔、模塊化的架構，通過全面的六階段重構實現了完整的平臺隔離。這種設計實現了最大程度的可維護性、零代碼重複，並支持無縫的跨平臺擴展。

✨ 架構成果

🎯 完整的平臺隔離

• 跨平臺工具 隔離在 shared/ 包中
• iOS特定代碼 包含在 platforms/ios/ 包中
• 所有組件 實現了清晰的關注點分離
• 面向未來 為 platforms/android/ 中的Android做好了準備

🔄 應用DRY原則

• 共享工具：日誌記錄器、異常處理、命令運行器
• 基礎配置：AppiumConfig、ServerConfig可重複使用
• 平臺配置：iOS特定設置獨立
• 當前/未來平臺之間 零重複

🛡️ 可維護且可擴展

• 自包含平臺：每個平臺完全獨立
• 統一接口：單一配置入口點
• 向後兼容：保留所有現有接口
• 專業結構：企業級組織

目錄結構

mobile-automation-mcp-server/
├── fastmcp_server.py          # 🚀 FastMCP 2.0服務器（主入口）
├── config/
│   └── settings.py           # 🔧 統一配置接口
├── shared/                   # 🌐 跨平臺工具和配置
│   ├── utils/               # 🛠️ 與平臺無關的工具  
│   │   ├── logger.py       # 📝 帶有表情符號的彩色日誌記錄
│   │   ├── exceptions.py   # ⚠️ 異常層次結構
│   │   └── command_runner.py # 💻  shell命令執行
│   └── config/             # ⚙️ 基礎配置類
│       └── base_settings.py # 📋 AppiumConfig、ServerConfig
├── platforms/ios/          # 🍎 iOS特定平臺代碼
│   ├── automation/         # 🤖 iOS自動化服務
│   │   ├── appium_client.py # 📱 iOS自動化客戶端
│   │   ├── screenshot_service.py # 📸 截圖處理
│   │   └── simulator_manager.py # 🎮 模擬器管理
│   ├── tools/             # 🔨 iOS特定MCP工具
│   │   ├── appium_tap_type_tool.py # ⌨️ 文本字段自動化
│   │   ├── find_and_tap_tool.py    # 👆 高級元素查找
│   │   ├── launch_app_tool.py      # 🚀 應用啟動
│   │   └── screenshot_tool.py      # 📷 截圖捕獲
│   └── config/            # ⚙️ iOS特定配置
│       └── ios_settings.py # 🍎 iOSConfig（XCUITest、iPhone）
├── screenshots/             # 📁 截圖存儲
├── Dockerfile              # 🐳 容器部署
├── Procfile                # 🚂 Railway部署
└── pyproject.toml          # 📦 依賴項和項目配置

🎯 實現的優勢

🔧 可用工具

take_screenshot

捕獲iOS模擬器截圖

{
  "filename": "optional_name.png",
  "device_id": "booted"
}

launch_app

啟動iOS應用程序

{
  "bundle_id": "com.apple.mobilesafari",
  "device_id": "booted"
}

find_and_tap

通過智能自動化查找並點擊UI元素

{
  "accessibility_id": "submitButton",
  "take_screenshot": true,
  "dismiss_after_screenshot": false
}

appium_tap_and_type

通過元素查找增強文本輸入

{
  "text": "Hello World!",
  "element_type": "textField",
  "timeout": 10
}

list_simulators

列出可用的iOS模擬器

{}

get_server_status

檢查服務器和Appium狀態

{}

🛠️ 開發

本地開發命令

# 在本地運行FastMCP服務器（使用uv）
uv run python mobile-automation-mcp-server/fastmcp_server.py

# 安裝依賴項（如果需要）
uv sync

# 開發模式（包含開發依賴項）
uv sync --dev

Appium設置

# 安裝Appium
npm install -g appium
appium driver install xcuitest

# 啟動Appium服務器
appium server --port 4723

架構開發

# 模塊化結構使開發更輕鬆：

# 處理共享工具（影響所有平臺）
cd shared/utils/

# 處理iOS特定功能  
cd platforms/ios/

# 處理配置
cd config/

# 添加新平臺（未來）
mkdir platforms/android/

🌐 雲部署

該服務器部署在Railway上，可通過以下方式訪問：

• HTTP端點：https://mcp-server-demo-production.up.railway.app/
• SSE端點：https://mcp-server-demo-production.up.railway.app/sse/

雲部署用於模擬iOS自動化響應，僅供演示使用。

📊 關鍵改進

🔍 故障排除

模擬器問題

# 列出可用的模擬器
xcrun simctl list devices

# 啟動模擬器
xcrun simctl boot "iPhone 16 Pro"

Appium連接問題

# 檢查Appium狀態
curl http://localhost:4723/status

# 重啟Appium
pkill -f appium && appium server --port 4723

📝 依賴項

核心依賴項通過 pyproject.toml 管理：

• fastmcp>=2.9.2 - FastMCP 2.0框架
• mcp>=1.0.0 - 傳統MCP協議
• aiohttp>=3.9.0 - 用於自動化的HTTP客戶端
• appium-python-client>=3.0.0 - iOS自動化
• pydantic>=2.4.0 - 數據驗證

使用以下命令安裝：

# 使用uv（推薦）
uv sync

# 或者使用pip
pip install -e .

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支
3. 遵循簡潔架構模式：
   • 共享工具 放入 shared/
   • 特定平臺代碼 放入 platforms/{platform}/
   • 配置 遵循模塊化層次結構
4. 添加全面的錯誤處理
5. 提交拉取請求

🚀 未來擴展

由於採用了簡潔的架構，添加新平臺非常簡單：

# 添加Android平臺（示例）
mkdir -p platforms/android/{automation,tools,config}

# 複用共享工具
from shared.utils import get_logger, AutomationMCPError
from shared.config import AppiumConfig, ServerConfig

# 創建Android特定配置
from platforms.android.config import AndroidConfig

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。