@customable/mobile-emulator-mcp (2.0.0)

Published 2025-10-10 11:41:33 +02:00 by jack in customable-mcp/mobile-emulator-mcp

Setup this registry in your project .npmrc file:

@customable:registry=

To install the package using npm, run the following command:

npm install @customable/mobile-emulator-mcp@2.0.0

or add it to the package.json file:

"@customable/mobile-emulator-mcp": "2.0.0"

For more information on the npm registry, see the documentation.

Mobile Emulator MCP Server

MCP Server for Mobile Emulator Automation - featuring iOS Simulator & Android Emulator control, screenshots, app installation, and UI testing capabilities.

🆕 What's New in v2.0.0

Version 2.0.0 brings a complete architectural overhaul with significant improvements:

🏗️ Modular Architecture

Refactored from 657-line monolithic code to clean, maintainable modules
82% reduction in main file size (117 lines)
Separated concerns: types, services, handlers, and tool definitions

✨ New Features

Pagination Support: Added limit and offset parameters to list_emulators
Platform-Aware Tools: Dynamic tool registration based on available platforms
Service-Oriented Design: Separate AndroidEmulatorService and IosSimulatorService

🔒 Type Safety

100% TypeScript type coverage (eliminated all any types)
Comprehensive interfaces for all data structures
Complete JSDoc documentation

🧪 Testing Infrastructure

Added Vitest testing framework with 13 unit tests
Test coverage reporting
Automated testing for tool definitions and types

📦 Dependencies

Updated MCP SDK from 1.0.4 to 1.20.0
Modern testing tools with coverage support

Features

Android Emulator Support

List running Android emulators
Start Android emulators by AVD name
Take screenshots
Install APK files
Simulate touch events (tap)
Input text
Retrieve device logs (logcat)

iOS Simulator Support

List running iOS simulators
Start iOS simulators
Take screenshots
Install app bundles (.app)
Retrieve system logs

Prerequisites

For Android:

Android SDK installed
adb (Android Debug Bridge) in PATH
Android emulators configured (AVD)

For iOS:

macOS required
Xcode installed
simctl available (comes with Xcode Command Line Tools)

Installation

npm install @customable/mobile-emulator-mcp

Configuration

Add to your MCP settings file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "mobile-emulator": {
      "command": "npx",
      "args": ["-y", "@customable/mobile-emulator-mcp"],
      "env": {
        "MOBILE_SCREENSHOT_DIR": "./screenshots",
        "MOBILE_COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

Environment Variables

MOBILE_SCREENSHOT_DIR: Directory where screenshots will be saved (default: ./screenshots)
MOBILE_COMMAND_TIMEOUT: Command execution timeout in milliseconds (default: 30000)

Available Tools

Cross-Platform

`list_emulators`

List all available and running mobile emulators/simulators with pagination support.

Parameters:

platform (optional): Filter by platform - "android", "ios", or "all" (default: "all")
limit (optional): Maximum number of results to return
offset (optional): Offset for pagination

Examples:

{
  "platform": "android"
}

{
  "platform": "all",
  "limit": 10,
  "offset": 0
}

Android-Specific Tools

`android_start_emulator`

Start an Android emulator by AVD name.

Parameters:

avdName (required): Android Virtual Device name

Example:

{
  "avdName": "Pixel_6_API_33"
}

`android_screenshot`

Take a screenshot from Android emulator.

Parameters:

deviceId (required): Emulator device ID (e.g., emulator-5554)

Example:

{
  "deviceId": "emulator-5554"
}

`android_install_app`

Install an APK on Android emulator.

Parameters:

deviceId (required): Emulator device ID
apkPath (required): Path to APK file

Example:

{
  "deviceId": "emulator-5554",
  "apkPath": "/path/to/app.apk"
}

`android_tap`

Simulate a tap on Android emulator screen.

Parameters:

deviceId (required): Emulator device ID
x (required): X coordinate
y (required): Y coordinate

Example:

{
  "deviceId": "emulator-5554",
  "x": 500,
  "y": 1000
}

`android_input_text`

Input text on Android emulator.

Parameters:

deviceId (required): Emulator device ID
text (required): Text to input

Example:

{
  "deviceId": "emulator-5554",
  "text": "Hello World"
}

`android_logs`

Get logcat output from Android emulator.

Parameters:

deviceId (required): Emulator device ID
lines (optional): Number of log lines to retrieve (default: 100)

Example:

{
  "deviceId": "emulator-5554",
  "lines": 200
}

iOS-Specific Tools

`ios_start_simulator`

Start an iOS simulator.

Parameters:

deviceId (required): iOS simulator device UUID

Example:

{
  "deviceId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

`ios_screenshot`

Take a screenshot from iOS simulator.

Parameters:

deviceId (required): iOS simulator device UUID

Example:

{
  "deviceId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

`ios_install_app`

Install an app on iOS simulator.

Parameters:

deviceId (required): iOS simulator device UUID
appPath (required): Path to .app bundle

Example:

{
  "deviceId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "appPath": "/path/to/MyApp.app"
}

`ios_logs`

Get system logs from iOS simulator.

Parameters:

deviceId (required): iOS simulator device UUID

Example:

{
  "deviceId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

Usage Examples

Starting an Android Emulator and Taking a Screenshot

// 1. List available emulators
const emulators = await client.callTool("list_emulators", {
  platform: "android"
});

// 2. Start an emulator
await client.callTool("android_start_emulator", {
  avdName: "Pixel_6_API_33"
});

// 3. Take a screenshot
const screenshot = await client.callTool("android_screenshot", {
  deviceId: "emulator-5554"
});

Installing and Testing an iOS App

// 1. Start iOS simulator
await client.callTool("ios_start_simulator", {
  deviceId: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
});

// 2. Install app
await client.callTool("ios_install_app", {
  deviceId: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  appPath: "/path/to/MyApp.app"
});

// 3. Take screenshot
await client.callTool("ios_screenshot", {
  deviceId: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
});

// 4. Check logs
const logs = await client.callTool("ios_logs", {
  deviceId: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
});

Troubleshooting

Android Issues

ADB not found:

Ensure Android SDK is installed
Add <SDK_PATH>/platform-tools to your PATH

Emulator not starting:

Check AVD name: emulator -list-avds
Ensure sufficient disk space and memory
Check for conflicting emulator instances

Screenshots failing:

Verify emulator is fully booted
Check device is online: adb devices

iOS Issues

simctl not found:

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

Simulator not starting:

Verify device UUID: xcrun simctl list devices
Check device is available and not already booted
Restart CoreSimulator service: sudo killall -9 com.apple.CoreSimulator.CoreSimulatorService

iOS only works on macOS:

iOS Simulator is only available on macOS with Xcode installed
Consider using Android for cross-platform development

Development

Building from Source

# Clone repository
git clone https://git.customable.host/customable-mcp/mobile-emulator-mcp.git
cd mobile-emulator-mcp

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

Testing

# Run unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Start in development mode
npm run watch

# In another terminal, test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

Limitations

iOS Simulator is only available on macOS
Direct UI element interaction on iOS requires additional frameworks (e.g., XCUITest)
Performance may vary based on host machine resources
Screenshot quality depends on emulator/simulator display settings

License

MIT

Author

Customable

Links

Development dependencies

ID	Version
@modelcontextprotocol/sdk	^1.20.0
@types/node	^22.10.2
@vitest/coverage-v8	^3.2.4
typescript	^5.7.2
vitest	^3.2.4

mcp ios android emulator simulator automation mobile testing

Details

npm

customable-mcp/mobile-emulator-mcp

2025-10-10 11:41:33 +02:00

Customable

Project website

MIT

latest

22 KiB

Assets (1)

mobile-emulator-mcp-2.0.0.tgz 22 KiB

Versions (2) View all

2.0.0

2025-10-10

1.0.0

2025-10-10

Issues

@customable/mobile-emulator-mcp (2.0.0)

Installation

About this package

Mobile Emulator MCP Server

🆕 What's New in v2.0.0

🏗️ Modular Architecture

✨ New Features

🔒 Type Safety

🧪 Testing Infrastructure

📦 Dependencies

Features

Android Emulator Support

iOS Simulator Support

Prerequisites

For Android:

For iOS:

Installation

Configuration

Environment Variables

Available Tools

Cross-Platform

list_emulators

Android-Specific Tools

android_start_emulator

android_screenshot

android_install_app

android_tap

android_input_text

android_logs

iOS-Specific Tools

ios_start_simulator

ios_screenshot

ios_install_app

ios_logs

Usage Examples

Starting an Android Emulator and Taking a Screenshot

Installing and Testing an iOS App

Troubleshooting

Android Issues

iOS Issues

Development

Building from Source

Testing

Limitations

License

Author

Links

Dependencies

Keywords

`list_emulators`

`android_start_emulator`

`android_screenshot`

`android_install_app`

`android_tap`

`android_input_text`

`android_logs`

`ios_start_simulator`

`ios_screenshot`

`ios_install_app`

`ios_logs`