shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mobile-automation-mcp-server

一个基于FastMCP 2.0和清洁架构的现代iOS自动化服务器，具有模块化设计、跨平台准备和云部署功能。

article

README

🚀 移动自动化iOS MCP服务器

这是一个基于FastMCP 2.0构建的现代化iOS自动化服务器，采用了简洁的架构，解决了iOS自动化测试的复杂性问题，为开发者提供了高效、可扩展的自动化解决方案。

License: MIT Python 3.11+ Platform: macOS FastMCP Architecture

这是一个基于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服务器实战

🏗️ 架构

移动自动化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          # 📦 依赖项和项目配置

🎯 实现的优势

| 方面 | 重构前 | 重构后 | |--------|-------------------|-------------------| | 结构 | iOS和共享代码混合 | 清晰的平台隔离 | | 可维护性 | 整体式 | 模块化且自包含 | | 可扩展性 | 仅支持iOS | 支持跨平台 | | 代码复用 | 可能存在重复 | 所有平台共享工具 | | 配置 | 单一设置文件 | 模块化配置层次结构 | | 组织 | 扁平结构 | 专业的企业结构 |

🔧 可用工具

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自动化响应，仅供演示使用。

📊 关键改进

| 功能 | 传统MCP | FastMCP 2.0 + 简洁架构 | |---------|----------------|----------------------------------| | 设置 | 复杂配置 | 简单的Python装饰器 | | 架构 | 整体式 | 模块化平台隔离 | | 代码复用 | 手动复制 | 共享工具包 | | 类型安全 | 手动验证 | 内置Pydantic模型 | | 错误处理 | 基本的try-catch | 丰富的上下文和日志记录 | | 部署 | 仅支持本地 | 支持Railway云部署 | | 可扩展性 | 难以扩展 | 易于添加新平台 | | 可维护性 | 复杂 | 清晰的关注点分离 |

🔍 故障排除

模拟器问题

# 列出可用的模拟器
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 文件。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端