sorinirimies/mobiledevice-mcp-zed-extension

Mobile Device MCP Server

A comprehensive Model Context Protocol (MCP) server for mobile device automation. Control Android and iOS devices programmatically through a standardized interface, perfect for testing, automation, and AI-assisted mobile app development.

🚀 Features

• 19 Mobile Automation Tools - Complete device control through MCP
• Full Android Support - 100% coverage for physical devices and emulators (19/19 tools)
• Comprehensive iOS Support - 95% coverage for simulators, 42% for physical devices (18/19 tools)
• Screenshot Capture - Visual device state with base64 PNG output (all platforms)
• UI Element Inspection - XML-based hierarchy parsing for Android
• App Lifecycle Management - Install, launch, terminate, and uninstall apps
• Touch & Gesture Automation - Tap, swipe, long press, and type
• Cross-Platform Build - Works on macOS, Linux, and Windows
• Native Binary + WASM - Standalone server and Zed extension support
• Clean Architecture - Modular, well-documented Rust codebase

📋 Available Tools

All tools use the mobile_device_mcp_* prefix for namespacing.

Device Information (5 tools)

Screen Interaction (6 tools)

Input (2 tools)

App Management (4 tools)

Navigation (2 tools)

Platform Summary:

• Android: 19/19 tools (100% coverage - all devices)
• iOS Simulator: 18/19 tools (95% coverage - macOS only)
• iOS Physical Device: 8/19 tools (42% coverage - basic automation)

Legend:

• ✅ Full support
• ✅* Simulator support (iOS) or partial support
• ⚠️** Limited support (requires additional tools like WebDriverAgent)

🏗️ Architecture

mobile-mcp-zed-extension/
├── src/
│   ├── main.rs              # Native MCP server (JSON-RPC 2.0)
│   ├── lib.rs               # Zed WASM extension
│   ├── types.rs             # Shared type definitions
│   ├── devices/
│   │   ├── android.rs       # Android automation (adb_client)
│   │   └── ios.rs           # iOS automation (xcrun simctl)
│   ├── mcp/
│   │   └── protocol.rs      # MCP protocol implementation
│   └── tools/
│       ├── definitions.rs   # Tool schemas (19 tools)
│       └── handlers.rs      # Tool implementations
├── extension.toml           # Zed extension manifest
└── Cargo.toml              # Dependencies

Tech Stack:
- Protocol: JSON-RPC 2.0 via MCP
- Android: adb_client crate + shell commands
- iOS: xcrun simctl + libimobiledevice (macOS only)
- Cross-Platform: Runs on macOS, Linux, and Windows
- XML Parsing: quick-xml for UI hierarchy
- Build: Native binary + WASM extension

📦 Installation

Prerequisites

Android Support (All Platforms): No additional tools required! The server uses a pure Rust ADB implementation (adb_client crate).

• Just enable USB debugging on your Android device
• The server handles all ADB communication natively
• No need to install android-platform-tools or adb separately

iOS Simulator Support (macOS only):

# Install Xcode Command Line Tools (REQUIRED for simctl)
xcode-select --install

# Verify
xcrun simctl list devices

iOS Real Device Support (macOS only):

# Install libimobiledevice (REQUIRED for physical devices)
brew install libimobiledevice

# Verify
idevice_id -l  # Lists connected physical devices

Build from Source

# Clone repository
git clone https://github.com/sorinirimies/mobiledevice-mcp-zed-extension
cd mobile-device-mcp

# Build native binary
# macOS (with iOS support)
cargo build --release --features "native-binary,ios-support"

# Linux/Windows (Android only)
cargo build --release --features native-binary

# Binary location
./target/release/mobile-device-mcp-server

# Or build Zed extension (WASM)
rustup target add wasm32-wasip1
cargo build --release --target wasm32-wasip1

Install as Zed Extension

1. Open Zed editor
2. Go to Extensions (Cmd+Shift+X)
3. Search for "Mobile Device MCP"
4. Click Install

Or manually:

# Copy to Zed extensions directory
mkdir -p ~/.config/zed/extensions
cp -r . ~/.config/zed/extensions/mobile-device-mcp

🚦 Quick Start

Using Just (Recommended)

Just is a command runner that simplifies common tasks:

# Install just
cargo install just

# Show all available commands
just

# Quick development setup
just dev-setup

# Build and run
just build
just run

# Run tests
just test

# Install Zed extension
just install-zed

# Format, lint, and test
just pre-commit

See the for all available commands.

Start MCP Server (Standalone)

# Run the server
./target/release/mobile-device-mcp-server

# Set debug mode (optional)
export MOBILE_DEVICE_MCP_DEBUG=1
./target/release/mobile-device-mcp-server

# Or using just
just run
just run-debug

Example MCP Requests

List Devices:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_list_available_devices",
    "arguments": {}
  }
}

Take Screenshot:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_take_screenshot",
    "arguments": {
      "device_id": "emulator-5554",
      "platform": "android"
    }
  }
}

List UI Elements:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_list_elements_on_screen",
    "arguments": {
      "device_id": "emulator-5554",
      "platform": "android",
      "filter": "Sign in"
    }
  }
}

🧪 Testing

# Run unit tests
just test

# Run tests with coverage
just test-coverage

# Run integration tests (requires connected device/emulator)
just test-integration

# Quick smoke test
just test-smoke

# Or manually
./scripts/test-all-tools.sh
./scripts/test-tools.sh

# Expected output:
# Total Tests:  18
# Passed:       18 ✅
# Failed:       0 ❌

📱 Device Setup

Android Emulator

# Start emulator
emulator -avd Pixel_6_API_34

# Verify connection
adb devices
# Output: emulator-5554   device

Android Physical Device

# Enable USB debugging on device
# Settings > Developer Options > USB Debugging

# Connect via USB and verify
adb devices

iOS Simulator (macOS)

# List available simulators
xcrun simctl list devices

# Boot a simulator
xcrun simctl boot "iPhone 15 Pro"

# Verify
xcrun simctl list devices | grep Booted

🔧 Configuration

Environment Variables

• MOBILE_DEVICE_MCP_DEBUG=1 - Enable debug logging
• MOBILE_PLATFORM=android|ios|auto - Default platform (auto = both)

Cargo Features

• native-binary - Build standalone MCP server (required for native builds)
• default - Build as Zed WASM extension

📚 Documentation

Comprehensive Guides

• - Complete iOS automation documentation
• - Complete Android automation documentation
• - Windows-specific setup and usage
• - Multi-OS deployment and testing
• - Detailed iOS vs Android comparison

📖 API Documentation

Tool Response Format

All tools return MCP-compliant responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool output here"
      }
    ]
  }
}

Screenshot responses use image type:

{
  "result": {
    "content": [
      {
        "type": "image",
        "data": "<base64-png-data>",
        "mimeType": "image/png"
      }
    ]
  }
}

Error Handling

Errors follow MCP error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "Device not found: emulator-5554"
  }
}

🛠️ Development

Quick Start with Just

# Complete development setup
just dev-setup

# Daily development workflow
just build        # Build debug binary
just test         # Run tests
just lint         # Run clippy
just fmt          # Format code
just pre-commit   # Run all checks before committing

# Watch for changes
just watch        # Auto-run tests on file changes
just watch-run    # Auto-restart server on file changes

Project Structure

• src/devices/ - Platform-specific device managers

  • android.rs - ADB client, UI automation, app management
  • ios.rs - simctl wrapper, screenshot, basic input

• src/tools/ - MCP tool definitions

  • definitions.rs - JSON schemas for all 19 tools
  • handlers.rs - Implementation logic for each tool

• src/mcp/ - Protocol layer

  • protocol.rs - JSON-RPC 2.0 structures

Adding New Tools

1. Define tool schema in src/tools/definitions.rs
2. Implement handler in src/tools/handlers.rs
3. Add dispatch case in src/main.rs
4. Update tests in scripts/test-all-tools.sh
5. Run just test to verify

Running Tests

# Using just (recommended)
just test                    # All tests
just test-integration        # Integration tests
just test-coverage          # With coverage report

# Or manually
cargo build --release --features native-binary
./scripts/test-all-tools.sh

# Run specific test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mobile_device_mcp_take_screenshot","arguments":{"device_id":"emulator-5554","platform":"android"}}}' | ./target/release/mobile-device-mcp-server

🐛 Troubleshooting

Android Issues

No devices detected:

• Enable USB debugging on your device (Settings → Developer Options → USB Debugging)
• The server's built-in ADB client will automatically detect connected devices
• For emulators, ensure they're running: emulator -list-avds
• The Rust adb_client handles all communication natively - no external ADB tools needed

Device unauthorized:

• Check your Android device screen for an authorization prompt
• Accept the "Allow USB debugging" dialog
• The server will automatically reconnect once authorized

iOS Issues

simctl not found:

# Install Xcode Command Line Tools
xcode-select --install

Simulator not booting:

# Kill all simulators
killall Simulator
# Boot specific device
xcrun simctl boot "iPhone 15"

🌐 Cross-Platform Support

Supported Platforms

Quick Setup:

• macOS: xcode-select --install (for iOS simulators), brew install libimobiledevice (for iOS devices)
• Linux: No additional tools needed (Android only)
• Windows: No additional tools needed (Android only)

Note: Android support uses a pure Rust ADB implementation - no platform tools required!

See for detailed instructions.

🔄 CI/CD

This project uses lightweight GitHub Actions workflows for essential checks:

Workflows

• CI (.github/workflows/ci.yml) - Runs on every push and PR

  • ✅ Tests (Ubuntu only)
  • ✅ Code formatting (cargo fmt)
  • ✅ Linting with Clippy

• Release (.github/workflows/release.yml) - Triggered on version tags

  • 📦 Builds binaries for Linux, macOS (ARM), and Windows
  • 📦 Creates GitHub releases
  • 📦 Uploads release artifacts

Local Checks

# Run formatting and linting
just fmt
just lint
just test

# Or all at once
just pre-commit

Creating a Release

# Tag and push
git tag -a "v0.2.0" -m "Release v0.2.0"
git push origin main --tags

The release workflow will automatically build and upload binaries for supported platforms.

🗂️ Changelog

See for release history.

Generated using git-cliff.

🤝 Contributing

Contributions welcome! Areas of interest:

1. iOS Feature Parity - Implement missing iOS tools (see feature parity doc)
2. Real Device Support - iOS real device automation
3. UI Testing - Visual element matching, assertions
4. Performance - Optimize XML parsing, caching
5. Platform Support - Windows/Linux improvements

Development Workflow

1. Fork and clone the repository
2. Run just dev-setup to configure your environment
3. Create a feature branch
4. Make your changes and add tests
5. Run just pre-commit to verify all checks pass
6. Submit a pull request

All PRs must pass CI checks before merging.

📄 License

MIT License - see file for details.

🙏 Acknowledgments

• adb_client - Rust ADB client library
• quick-xml - Fast XML parsing
• MCP Protocol - Model Context Protocol specification
• Zed Editor - Extension platform
• just - Command runner for development tasks
• git-cliff - Changelog generator

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Version: 0.1.0
Status: Production Ready (Android Full, iOS Simulator), Beta (iOS Physical Devices)
Last Updated: November 1, 2024
Platform Coverage: macOS (Full), Linux (Android), Windows (Android)