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 文件。