# mobile-mcp **Repository Path**: cong_wa/mobile-mcp ## Basic Information - **Project Name**: mobile-mcp - **Description**: 移动端UI自动化神器，支持ios和android 传统自动化测试需要学 Appium、写代码、定位元素、调试维护。现在只需对 Cursor 说"帮我测试登录流程"，AI 自动操作手机并生成测试脚本，2 分钟搞定。不用写代码、不用记 API，UI 改了 AI 自动适配，开箱即用。 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 38 - **Created**: 2026-02-09 - **Last Updated**: 2026-02-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 📱 Mobile MCP Agent > 移动端 AI 自动化测试平台 —— MCP 工具 + AI Agent + 可视化操控台

[![PyPI](https://img.shields.io/pypi/v/mobile-mcp-ai.svg?style=flat-square&color=blue)](https://pypi.org/project/mobile-mcp-ai/) [![Python](https://img.shields.io/badge/python-3.8+-green.svg?style=flat-square)](https://www.python.org/) [![License](https://img.shields.io/badge/license-Apache%202.0-orange.svg?style=flat-square)](LICENSE) [![Android](https://img.shields.io/badge/Android-支持-brightgreen.svg?style=flat-square&logo=android)](https://developer.android.com/) [![iOS](https://img.shields.io/badge/iOS-支持-black.svg?style=flat-square&logo=apple)](docs/iOS_SETUP_GUIDE.md) **⭐ 觉得有用？给个 Star 支持一下！** **📱 支持 Android 和 iOS 双平台** [English](README_EN.md)

--- ## 📖 项目简介 Mobile MCP Agent 是一个移动端 AI 自动化测试平台，包含三个可独立使用的层次： | 层次 | 说明 | 技术栈 | 文档 | |:---:|------|------|:---:| | **MCP Server** | 39 个移动端自动化工具，可独立配合 Cursor / Claude 使用 | Python · MCP 协议 · PyPI | [MCP 文档](docs/MCP_README.md) | | **AI Agent** | 智能测试执行引擎，自动编排工具调用、范式降级、结果验证 | LangChain · LangGraph | [Agent 文档](agent-app/README.md) | | **Electron 操控台** | 可视化界面，设备预览、测试流程编排、实时操作日志 | Electron · React · TailwindCSS | 本文档 | > **只想用 MCP 工具配合 Cursor / Claude？** 请直接查看 👉 [MCP 使用文档](docs/MCP_README.md) --- ## 🎬 演示

![演示动图](docs/videos/demo.gif) *[查看高清视频 →](docs/videos/demo.mp4)*

![软件运行效果](images/agent1.jpg) *Agent 自动化测试执行效果*

--- ## ✨ 核心特性

### 🧠 AI Agent 智能执行基于 LangChain + LangGraph 的测试 Agent，自动编排工具调用，按步骤执行测试用例	### 🔄 三范式自动降级元素交互 → SoM 视觉 → 坐标定位，逐级降级，确保操作成功率
### 🖥️ 可视化操控台 Electron 桌面应用，设备实时预览、测试流程编排、操作日志时间轴	### 🔧 MCP 工具独立可用 39 个工具通过 `pip install mobile-mcp-ai` 安装，可直接配合 Cursor / Claude 使用
### 🎯 双平台支持 Android + iOS 双平台，元素树 + 视觉坐标双引擎	### 🛡️ 智能验证机制操作结果自动验证，前置条件检查，测试报告自动生成

--- ## 📱 平台支持 | 平台 | 支持状态 | 系统要求 | 配置指南 | |:---:|:---:|:---:|:---:| | **Android** | ✅ 完整支持 | Windows / macOS / Linux | 开箱即用 | | **iOS** | ✅ 完整支持 | macOS（必须） | [iOS 配置指南 →](docs/iOS_SETUP_GUIDE.md) | --- ## 🏗️ 系统架构 ``` ┌──────────────────────────────────────────────────────┐ │ Electron 操控台 (frontend/) │ │ React · TailwindCSS · Shadcn UI · oRPC │ │ 设备预览 · 测试编排 · 聊天交互 · 操作日志时间轴 │ └──────────────────┬───────────────────────────────────┘ │ HTTP / SSE ┌──────────────────▼───────────────────────────────────┐ │ AI Agent (agent-app/) │ │ LangChain · LangGraph · FastAPI · SSE Stream │ │ 智能编排 · 范式降级 · 截图优化 · 操作日志 · 重试机制 │ └──────────────────┬───────────────────────────────────┘ │ MCP 协议 (stdio) ┌──────────────────▼───────────────────────────────────┐ │ MCP Server (pip install mobile-mcp-ai) │ │ 39 个移动端自动化工具 · Android + iOS │ └──────────────────┬───────────────────────────────────┘ │ ADB / WebDriverAgent 📱 移动设备 ``` --- ## 🚀 快速开始 ### 前置条件 | 工具 | 用途 | 安装 | |------|------|------| | **Python 3.8+** | MCP Server & Agent | [python.org](https://www.python.org/) | | **Node.js 18+** | Electron 操控台 | [nodejs.org](https://nodejs.org/) | | **pnpm** | 前端包管理 | `npm install -g pnpm` | | **uv** | Agent 依赖管理 | `pip install uv` | | **ADB** | Android 设备连接 | Android SDK Platform Tools | | **Git** | 源码获取 | [git-scm.com](https://git-scm.com/) | ### 第一步：克隆项目 ```bash git clone https://gitee.com/cong_wa/mobile-mcp.git cd mobile-mcp ``` ### 第二步：连接移动设备 **Android 用户：** ```bash # 开启手机 USB 调试，用数据线连接电脑 adb devices # 看到设备列表即连接成功 ``` **iOS 用户：** ```bash # 安装依赖 pip install tidevice facebook-wda brew install libimobiledevice # 检查连接 tidevice list ``` > 📖 iOS 需要额外配置 WebDriverAgent，详见 [iOS 配置指南](docs/iOS_SETUP_GUIDE.md) ### 第三步：启动 MCP Server（SSE 模式） Agent 和 Electron 操控台都需要 MCP Server 以 SSE 模式运行： ```bash # 安装 MCP Server pip install mobile-mcp-ai # 以 SSE 模式启动（默认端口 3100） mobile-mcp --sse ``` > 💡 SSE 模式下 MCP Server 会在 `http://localhost:3100/sse` 提供服务 ### 第四步：启动 AI Agent 后端 ```bash cd agent-app # 复制并编辑配置文件 cp .env.example .env # 编辑 .env，填入 LLM API Key（必填） ``` `.env` 关键配置： ```bash # LLM 配置（必填） LLM_MODEL=openai:gpt-4o # 模型，格式: provider:model LLM_API_KEY=sk-xxx # API Key LLM_BASE_URL=https://api.openai.com/v1 # API 地址 # Agent 服务器 AGENT_HOST=0.0.0.0 AGENT_PORT=8088 ``` 启动 Agent： ```bash # 安装依赖 uv sync # 启动 Agent HTTP 服务 uv run uvicorn mobile_agent.api.app:app --host 0.0.0.0 --port 8088 ``` Agent 启动后会自动通过 stdio 连接 MCP Server。 ### 第五步：启动 Electron 操控台 ```bash cd frontend # 安装依赖 pnpm install # 启动开发模式 pnpm start ``` 操控台默认连接 `http://localhost:8088/api/v1`，如需修改，可在操控台的**设置页面**中更改后端地址。 --- ## ⚙️ 部署配置 ### 后端服务地址配置 Electron 操控台需要连接 AI Agent 后端服务，支持以下配置方式（优先级从高到低）： | 方式 | 说明 | 适用场景 | |------|------|------| | **操控台设置页面** | 在 UI 中直接修改后端地址（保存到 localStorage） | 最方便，推荐日常使用 | | **环境变量** | 设置 `VITE_API_BASE` 环境变量 | 构建时指定 | | **默认值** | `http://localhost:8088/api/v1` | 本地开发 | **设置页面修改（推荐）：** 打开 Electron 操控台 → 左侧导航栏点击「设置」 → 修改相关配置： - **LLM 配置**：模型、API Key、Base URL - **MCP Server 地址**：MCP Server 的 SSE 地址（默认 `http://localhost:3100/sse`） - **Agent 行为**：最大迭代次数、System Prompt - **中间件**：操作日志、截图优化、重试策略 **环境变量方式：** ```bash # 构建时指定后端地址 VITE_API_BASE=http://your-server:8088/api/v1 pnpm start ``` ### 远程部署如果 Agent 后端部署在远程服务器： ```bash # 1. 远程服务器：启动 MCP Server mobile-mcp --sse --host 0.0.0.0 --port 3100 # 2. 远程服务器：启动 Agent cd agent-app uv run uvicorn mobile_agent.api.app:app --host 0.0.0.0 --port 8088 # 3. 本地：操控台连接远程 Agent # 在操控台设置页面将后端地址改为：http://<远程IP>:8088/api/v1 ``` --- ## � 项目结构 ``` mobile-mcp/ ├── mcp_tools/ # MCP Server 源码 ├── core/ # MCP 核心模块（元素定位、截图、设备管理等） ├── mobile_mcp/ # PyPI 包入口 ├── agent-app/ # AI Agent 后端 │ ├── src/mobile_agent/ # Agent 源码 │ │ ├── core/ # Agent 核心（配置、MCP连接、Agent构建） │ │ ├── api/ # FastAPI 端点 │ │ ├── prompts/ # System Prompt │ │ ├── middleware/ # 中间件（日志、截图优化、重试） │ │ └── cli/ # CLI 交互模式 │ └── .env.example # 环境变量示例 ├── frontend/ # Electron 操控台 │ ├── src/ # React 源码 │ └── package.json ├── docs/ # 文档 │ ├── MCP_README.md # MCP 使用文档（中文） │ ├── MCP_README_EN.md # MCP 使用文档（English） │ ├── iOS_SETUP_GUIDE.md # iOS 配置指南 │ └── ... ├── config.py # MCP Server 配置 ├── env.example # MCP Server 环境变量示例 ├── setup.py # PyPI 打包配置 ├── requirements.txt # MCP Server 依赖 └── README.md # 本文件 ``` --- ## � 各组件独立使用 ### 只用 MCP Server（配合 Cursor / Claude）不需要 Agent 和 Electron，直接用 MCP 工具： ```bash pip install mobile-mcp-ai ``` 详见 👉 [MCP 使用文档](docs/MCP_README.md) ### 只用 Agent CLI 模式不需要 Electron 操控台，用命令行交互： ```bash cd agent-app uv sync uv run python -m mobile_agent.cli.interactive ``` ``` 🤖 Mobile Agent 已启动，输入任务开始操作手机 👤 > 打开微信，进入朋友圈 🤖 好的，我来帮你打开微信并进入朋友圈... ``` --- ## ❓ 常见问题 ### Q: 启动后操控台连不上后端？ 1. 确认 Agent 已启动且监听端口正确（默认 `8088`） 2. 在操控台「设置」页面检查后端地址是否正确 3. 如果跨机部署，确认防火墙放行了端口 ### Q: MCP Server 连不上设备？ - **Android**: 确认 `adb devices` 能看到设备，USB 调试已开启 - **iOS**: 确认 `tidevice list` 能看到设备，WebDriverAgent 已配置 ### Q: Agent 报错 LLM 连接失败？检查 `agent-app/.env` 中的配置： - `LLM_API_KEY` 是否正确 - `LLM_BASE_URL` 是否可访问 - 在操控台设置页面点击「测试连接」验证 --- ## 📞 联系作者

*扫码加入 QQ 交流群（群号：1080722489）*

--- ## 🙏 致谢本项目的 MCP 工具部分 fork 自 [mobile-mcp](https://gitee.com/chang-xinping/mobile-mcp) 项目，感谢原作者的开源贡献！ ## 📄 License Apache 2.0 ---

[Gitee](https://gitee.com/cong_wa/mobile-mcp) · [GitHub](https://github.com/congwa/mobile-agent) · [PyPI](https://pypi.org/project/mobile-mcp-ai/) **🚀 让移动端测试更简单**