DOCSEARCHbyAlgolia
Submit Docs

Mobile Next MCP

repository·main·Indexed 26 days ago

https://github.com/mobile-next/mobile-mcp

A Model Context Protocol (MCP) server providing a platform-agnostic API for automating iOS and Android devices, including simulators, emulators, and real hardware. It enables LLMs and Agents to perform device management, app lifecycle control, screen interactions (clicks, swipes, screenshots), input navigation, and crash report retrieval without requiring platform-specific expertise in XCUITest or Espresso.

Tokens
5.5K
Snippets
6
Records
51
Agent score
87%

What's inside @mobilenext/mobile-mcp

  1. Overview of Mobile Next MCP

    main
    Mobile Next is a Model Context Protocol (MCP) server designed for scalable mobile automation and development. It provides a platform-agnostic interface that allows LLMs and Agents to interact with iOS and Android devices (simulators, emulators, and real hardware) without requiring platform-specific expertise like XCUITest or Espresso. The server uses an accessibility-first approach, driving interactions through the native accessibility tree for speed and efficiency, falling back to coordinate-based interactions when necessary.

  2. Install Mobile MCP in various IDEs and CLI tools

    main

    Mobile MCP can be installed in several MCP-compatible clients. The standard configuration uses npx to run @mobilenext/mobile-mcp@latest.

    Standard JSON Configuration

    Use this for tools like Claude Desktop, Cline, or Windsurf:

    {
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

    Tool-Specific Installation Commands

    • Amp CLI: amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
    • Claude Code: claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
    • Codex CLI: codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
    • Gemini CLI: gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
    • Copilot CLI: Use /mcp add interactively.
    • Cursor: Use the Cursor MCP Install Link or manually add a command type server with npx -y @mobilenext/mobile-mcp@latest.
    • Goose: Add a custom extension with type STDIO and command npx -y @mobilenext/mobile-mcp@latest.
    • Windsurf: Add a new server with command type using npx @mobilenext/mobile-mcp@latest.

  3. Verify Mobile MCP installation

    main

    After adding the configuration, verify the installation by calling the mobile_list_available_devices tool.

    • Success: The tool returns a list of connected simulators, emulators, and/or real devices.
    • Failure (Empty list): Ensure a simulator or emulator is currently running, or that a physical device is connected and authorized.
    mobile_list_available_devices

  5. Install the Mobile MCP server

    main

    To install Mobile MCP, add the server to your MCP configuration file (e.g., claude_desktop_config.json or your IDE's MCP settings). The server is executed via npx and does not require a separate global installation.

    Prerequisites

    • Node.js v20+
    • Android targets: Android Platform Tools with adb available on your PATH.
    • iOS targets (macOS only): Xcode command line tools.
    • Active target: At least one booted iOS Simulator, running Android emulator, or a connected real device must be available.
    {
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

  6. Run Mobile MCP in SSE Server Mode

    main

    By default, Mobile MCP runs over stdio. To run it as an SSE (Server-Sent Events) server, use the --listen flag. This allows clients to connect via HTTP.

    To bind to localhost:3000:

    npx @mobilenext/mobile-mcp@latest --listen 3000

    To bind to a specific interface (e.g., 0.0.0.0 for network access):

    npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000

    Configure your MCP client to connect to http://<host>:3000/mcp.

  7. Authenticate SSE server with Bearer tokens

    main
    The SSE (Server-Sent Events) server supports optional Bearer-token authentication. To enable this, use the --listen flag when starting the server and provide the token via the MOBILEMCP_AUTH environment variable.

  8. Platform Support and Setup Requirements

    main

    Mobile MCP supports the following targets:

    TargetSupportedSetup Requirements
    iOS Simulator✅Xcode + a booted simulator (xcrun simctl)
    iOS Real Device✅go-ios + WebDriverAgent + tunnel
    Android Emulator✅Android SDK + running emulator (adb)
    Android Real Device✅adb + USB debugging enabled & authorized

    General Prerequisites:

    • Node.js v20+
    • Xcode command line tools
    • Android Platform Tools
    • An MCP-compatible client (e.g., Claude MCP, OpenAI Agent SDK, Copilot Studio)

  9. Run Mobile MCP in Headless Mode

    main

    You can run Mobile MCP with emulators or simulators running in the background.

    Android

    1. Start an emulator using avdmanager or emulator commands.
    2. Run Mobile MCP with your desired flags.

    iOS

    1. Ensure Xcode is installed.
    2. Boot a simulator instance using xcrun simctl:
      xcrun simctl boot "iPhone 16"
    3. Run Mobile MCP.

  10. Configure Authorization for SSE Server

    main

    To secure an SSE server, set the MOBILEMCP_AUTH environment variable. This requires all incoming requests to include a Bearer token in the Authorization header.

    Example:

    MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000

    Clients must then send the header: Authorization: Bearer my-secret-token.