Content
# Mobile MCP AI
<div align="center">
[](https://pypi.org/project/mobile-mcp-ai/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/test111ddff-hash/mobile-mcp-ai)
**AI-Powered Mobile Test Automation Framework**
[English](#english)
**Find it useful? Give us a ⭐ Star!**
</div>
---
## English
Mobile test automation framework that supports natural language testing through Cursor AI and generates pytest test cases.
### Features
#### 🎯 Natural Language Driven Intelligent Testing
- **Zero-Code Testing**: Describe test flows in natural language, AI automatically understands and executes each step
- **Smart Interaction**: Automatically handles exceptions, intelligent retry and error recovery
- **Low Barrier**: No need to write complex scripts, reducing testing barriers by 90%+
#### 🎨 Smart Locator Strategy
- **Multi-Level Fallback**: Intelligent multi-layer locator strategy fallback
- **High Success Rate**: 95%+ locator success rate, average time <100ms (cache hit <5ms)
- **Smart Scoring Algorithm**: Multi-dimensional scoring based on type matching, text matching, position weight, etc.
- **Multimodal AI**: Supports visual recognition for complex locator scenarios
#### 🚀 One-Click pytest Script Generation
- **Auto Script Generation**: Automatically generates standard pytest format test scripts based on operation history
- **100% Executable**: Uses verified locator methods to ensure scripts can run directly
- **Full Support**: Supports all pytest features including fixtures, parameterization, Allure reports, etc.
- **Batch Execution**: Generated scripts can be run together with other test cases
#### 🌐 Cross-Platform Support
- **Dual Platform Support**: Perfect support for Android and iOS platforms
- **Unified Interface**: 80%+ code reuse through adapter pattern
- **Device Management**: Automatically detects and manages connected devices, supports multi-device switching
#### 🤖 Deep Integration with Cursor AI
- **MCP Protocol**: Based on Model Context Protocol, seamlessly integrated with Cursor AI
- **20+ Tools**: Provides rich mobile operation tools, intelligently called by AI
- **AI Enhancement**: Supports multi-platform AI (Cursor/Claude/OpenAI/Gemini) auto-detection and switching
#### ⚡ Performance Optimization
- **XML Cache Mechanism**: 1-second TTL cache reduces duplicate read overhead
- **Element Pre-filtering**: Pre-filter by type, position, attributes, reducing 50%+ traversal
- **Single Read Reuse**: Avoids 400-1000ms duplicate XML read overhead
### Installation
```bash
pip install mobile-mcp-ai
```
### Quick Start
#### 1. Configure Cursor MCP
Create `.cursor/mcp.json` file (in project root or user directory `~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"mobile-mcp-ai": {
"command": "python",
"args": ["-m", "mobile_mcp.mcp.mcp_server"],
"env": {
"MOBILE_DEVICE_ID": "auto"
}
}
}
}
```
For detailed configuration, see: [Start Guide](docs/START_GUIDE.md)
#### 2. Connect Device
```bash
# Android device
adb devices # Confirm device is visible
```
#### 3. Restart Cursor
After configuration, completely exit and restart Cursor.
#### 4. Start Using
After restarting Cursor, describe test flows in natural language in the chat window:
```
Help me test the login function:
1. Launch com.example.app
2. Click login button
3. Enter username admin
4. Enter password password
5. Click submit button
6. Verify page displays "Welcome"
```
AI will automatically understand and execute each step, intelligently locate elements, and handle exceptions.
### Usage Examples
#### Execute Tests
Describe test flows in natural language in Cursor, and AI will automatically execute each step.
#### Generate pytest Scripts
After executing tests, you can generate pytest format test scripts:
```
Help me generate a pytest test script, test name is "Post Test", package name is com.example.app, filename is test_post
```
Generated scripts are saved in the `tests/` directory and can be run directly:
```bash
pytest tests/test_post.py -v
```
### Available Tools
After configuration, Cursor AI can use the following tools:
- **Device Management**: `mobile_list_devices`, `mobile_get_current_package`, `mobile_get_screen_size`, etc.
- **Interaction**: `mobile_click`, `mobile_input`, `mobile_swipe`, `mobile_press_key`, etc.
- **Page Analysis**: `mobile_snapshot`, `mobile_take_screenshot`, `mobile_assert_text`
- **App Management**: `mobile_launch_app`, `mobile_list_apps`, `mobile_install_app`, etc.
- **AI Enhancement**: `mobile_generate_test_script` (generate pytest scripts)
See documentation for complete tool list and usage instructions.
### Documentation
- [Start Guide](docs/START_GUIDE.md) - Complete installation and configuration steps
- [How to Generate Test Scripts](docs/START_GUIDE.md) - Test script generation guide
### License
Apache License 2.0
### Contributing
Issues and Pull Requests are welcome!
<div align="center">
**⭐ Find it useful? Give us a Star! ⭐**
[](https://github.com/test111ddff-hash/mobile-mcp-ai/stargazers)
[GitHub Repository](https://github.com/test111ddff-hash/mobile-mcp-ai) | [PyPI](https://pypi.org/project/mobile-mcp-ai/)
Made with ❤️ by Douzi Team
</div>
