Mobile Automation Mcp Server

开发 Python

🚀 移动自动化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：本地开发

前提条件
- macOS（iOS自动化必需）
- Python 3.11+
- uv（推荐）或pip
- 安装了iOS模拟器的Xcode
- Node.js（用于Appium）

安装

git clone https://github.com/iHackSubhodip/mcp-server-demo.git
cd mcp-server-demo

# 使用uv（推荐）
uv sync

# 或者使用pip（传统方式）
pip install -e .

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

🎯 实现的优势

方面	重构前	重构后
结构	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 .

🤝 贡献

分叉仓库
创建功能分支
遵循简洁架构模式：
- 共享工具 放入 shared/
- 特定平台代码 放入 platforms/{platform}/
- 配置遵循模块化层次结构
添加全面的错误处理
提交拉取请求

🚀 未来扩展

由于采用了简洁的架构，添加新平台非常简单：

# 添加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 文件。

0 条评论
分类：开发