# Mobile Next — full documentation > Concatenated Markdown of every docs page. Source of truth: https://mobilenext.ai/docs/ # https://mobilenext.ai/docs/api/account ## Get current user {#get-me} The authenticated user. To learn which organizations the caller belongs to (and their role in each), call GET /api/v1/organizations. --- # https://mobilenext.ai/docs/api/api-keys ## List API keys {#list-api-keys} Lists all API keys in the selected organization, visible to every member of it. Secrets are never returned; only a short suffix is shown to help identify each key. Requires an interactive (JWT) session: an API key cannot list keys. Use the X-Organization-Id header to choose the organization; otherwise the caller's default organization is used. } /> ## Create an API key {#create-api-key} Creates a new API key in the selected organization and returns its secret. The full secret is shown only once, in this response; it is never retrievable again. Requires an interactive (JWT) session: an API key cannot create another API key. Use the X-Organization-Id header to choose which organization the new key belongs to. A newly created API key. apiKey is the full secret and is returned only here, only once. ## Delete an API key {#delete-api-key} Permanently deletes an API key in the organization. Any key in the organization can be deleted (not only the caller's own). Requires an interactive (JWT) session: an API key cannot delete keys. Requires a read/write or admin role; read-only members cannot delete keys. Use the X-Organization-Id header to choose the organization; otherwise the caller's default organization is used. --- # https://mobilenext.ai/docs/api/billing ## Get billing balance {#get-billing-balance} --- # https://mobilenext.ai/docs/api/chats ## List chats in a session {#list-chats} Chats belonging to the session, oldest first. A chat exists only inside a session; there is no way to address one without it. Visible to every member of the organization that owns the session. } /> } /> ## Create a chat {#create-chat} Creates a chat in the session. Bind the chat to an allocated device by setting metadata.deviceId; the assistant's device tools then act on that device. Every action is still authorized against the caller, never against the bound device. } /> A conversation with the assistant, inside a session. } /> ## Get a chat {#get-chat} Returns a chat in the session. A chat id that belongs to a different session is not found, even within the same organization. A conversation with the assistant, inside a session. } /> ## List messages in a chat {#list-chat-messages} The most recent messages of the chat, returned oldest first, with cursor pagination backwards into older history. Each assistant message includes the tool calls it made, so a client can rebuild the conversation — text and tool calls — after a page reload. Follow nextCursor with ?before= to load older messages. } /> } /> } /> } /> ## Post a message and run the assistant {#create-chat-message} Appends a user message and runs the assistant. Three modes: - default (async): responds 202 with the assistant message in status "running". Follow execution.eventsUrl to stream it. - mode=sync: runs inline and responds 201 with the completed assistant message and its tool calls. - stream=true: responds with a text/event-stream of execution and assistant.message events. Set execute=false to store the user message without running the assistant. } /> ## Get a message {#get-chat-message} } /> } /> } /> ## Stream a message's execution events {#stream-chat-message-events} Server-Sent Events for one assistant message: execution.started, assistant.message.started, assistant.message.delta, tool_call.created, tool_call.completed, assistant.message.completed, execution.completed|failed. Safe to call after a disconnect: a still-running execution replays its events from the start, and a finished one replays its stored final state — the stored replay emits the message text as a single delta and no tool_call events. Clients must therefore not render the message's persisted text and also reattach here, or the text appears twice. ## List a message's tool calls {#list-chat-message-tool-calls} } /> ## Cancel a running message {#cancel-chat-message} Requests cancellation of a message whose execution is still running. Requires a read/write or admin role. } /> } /> } /> --- # https://mobilenext.ai/docs/api/devices ## List devices in a session {#list-devices} Devices attached to the session, newest first. Visible to every member of the organization that owns the session. } /> } /> ## Allocate a device {#allocate-device} Allocates a device matching the given filters and attaches it to the session. Uses the same filter DSL as the fleet.allocate RPC. Allocation is asynchronous: the device is returned immediately with status "provisioning" or "queued" and becomes usable once its status is "ready". Poll GET /sessions/\{sessionId\}/devices/\{deviceId\} to observe readiness. } /> } /> ## Get a device {#get-device} Returns a device attached to the session. Visible to every member of the organization that owns the session. } /> ## Release a device {#release-device} Releases a device, stopping billing and returning it to the fleet. Returns the device with its updated status. Idempotent: releasing an already-released device is a no-op. } /> --- # https://mobilenext.ai/docs/api/instances ## List instances in a session {#list-instances} Instances attached to the session, newest first. Visible to every member of the organization that owns the session. } /> } /> ## Allocate an instance {#create-instance} Allocates a new instance (a build/automation machine) attached to the session. Provisioning is asynchronous: the instance is returned immediately with status "provisioning" and becomes usable once its status is "ready". Poll GET /sessions/\{sessionId\}/instances/\{instanceId\} to observe readiness. A build/automation machine allocated to a session. } /> ## Get an instance {#get-instance} Returns an instance attached to the session. Visible to every member of the organization that owns the session. A build/automation machine allocated to a session. } /> ## Release an instance {#release-instance} Releases an instance, stopping billing and tearing it down. Returns the instance with its updated status. Idempotent: releasing an already-released instance is a no-op. A build/automation machine allocated to a session. } /> --- # https://mobilenext.ai/docs/api/intro # Mobile Next Cloud API Public REST API for MobileFleet. Used by mobilewright reporters and dashboard clients. All endpoints require a Bearer token starting with mob_. Org-scoped requests act on the caller's active organization; to act on a different organization the caller belongs to, send its id in the X-Organization-Id header. ## Base URL ``` https://api.mobilenext.ai ``` ## Authentication All endpoints require a Bearer token that starts with `mob_`: ``` Authorization: Bearer mob_... ``` Org-scoped requests act on the caller's active organization. To act on a different organization you belong to, send its id in the `X-Account-Id` header. --- # https://mobilenext.ai/docs/api/invitations ## List invitations addressed to the caller {#list-incoming-invitations} Pending, unexpired invitations addressed to the caller's email across all organizations. Interactive (JWT) sessions only. } /> } /> ## Accept an invitation {#accept-invitation} Accepts an invitation addressed to the caller, joining the organization with the invited role. Interactive (JWT) sessions only. ## Reject an invitation {#reject-invitation} Rejects (declines) an invitation addressed to the caller. Interactive (JWT) sessions only. ## List pending invitations for the organization {#list-organization-invitations} Returns the pending invitations for the organization. Admin only. } /> ## Invite a new member to the organization {#invite-organization-member} Creates a pending invitation for an email with the given role. Admin only. Fails if the email already belongs to a member or already has a pending invitation. ## Revoke a pending invitation {#revoke-organization-invitation} Revokes a pending invitation in the organization. Admin only. --- # https://mobilenext.ai/docs/api/organizations ## List organizations the caller belongs to {#list-organizations} } /> ## Create a new organization {#create-organization} Creates an organization owned by the caller (who becomes its admin). The name is required, cannot be "Personal", and cannot duplicate the name of an organization the caller already belongs to. ## List organization members {#list-organization-members} Returns the active members of the organization. The caller must be a member of the organization. } /> --- # https://mobilenext.ai/docs/api/sessions ## List sessions {#list-sessions} Sessions in the selected organization, visible to every member of it, newest first, with cursor pagination. The organization is chosen by the X-Organization-Id header, or the organization the API key is bound to, otherwise the caller's default organization. } /> } /> } /> } /> } /> } /> ## Create a session {#create-session} Creates an empty session container. Attach resources to it separately: use fleet.allocate with sessionId to link a device, or allocate an instance with sessionId. } /> } /> } /> } /> } /> ## Get a session {#get-session} Returns a session in the selected organization, visible to every member of it. The organization is chosen by the X-Organization-Id header, or the organization the API key is bound to, otherwise the caller's default organization. } /> } /> } /> } /> } /> --- # https://mobilenext.ai/docs/api/test-results ## List test results {#list-test-results} Test results in the selected organization, visible to every member of it. The organization is chosen by the X-Organization-Id header, or the organization the API key is bound to, otherwise the caller's default organization. } /> ## Create a test result {#create-test-result} Called by the mobilewright reporter once a test run completes. Returns the created record including its id, which is used for subsequent asset uploads. The result is filed under the organization the API key is bound to, or the X-Organization-Id header, otherwise the caller's default organization. ## Get a test result {#get-test-result} ## List assets for a test result {#list-test-result-assets} Returns all uploaded assets (e.g. trace.zip, screenshots.zip) for this test result. } /> ## Upload an asset {#upload-test-result-asset} Uploads a binary asset attached to a test result. Use multipart/form-data with the file and its name. In future, a presignedUrl parameter may be added to return an S3 pre-signed URL instead of accepting the upload directly. ## Download an asset {#download-test-result-asset} Streams the raw binary content of a specific asset. --- # https://mobilenext.ai/docs/architecture **There is one runtime underneath everything.** MobileCLI is the single API that speaks to every device. Mobilewright and Mobile MCP are clients of it, CI and scripts call it directly, and Mobile Next Cloud is that same runtime — managed and scaled for you. So the stack is an hourglass: many ways in on top, one waist in the middle, every device on the bottom. ```mermaid graph TD Developer["Developer/SDET"] --> Mobilewright["Mobilewright"] AIAgent["AI Agent / LLM"] --> MobileMCP["Mobile MCP"] Automation["CI / scripts"] --> Mobilewright Automation --> Core Mobilewright --> Core MobileMCP --> Core Core[["MobileCLI — one API for every device"]] Core --> DeviceKit["DeviceKit (on-device runtime)"] DeviceKit --> iOS["iOS"] DeviceKit --> Android["Android"] ``` The same MobileCLI runs in two places, unchanged — on your machine, or behind the cloud: ```mermaid graph LR subgraph Local["Your machine — free to self-host"] L["MobileCLI → DeviceKit → your device"] end subgraph Cloud["Mobile Next Cloud — real devices, on demand"] C["API → many MobileCLI → DeviceKit → real device"] end ``` Because local and cloud are the same stack, moving to the cloud is a connection-string change, not a rewrite. ## Which piece do I use? | You are… | You use… | | --- | --- | | A developer writing mobile tests or automating mobile apps | **Mobilewright** | | An AI agent (Claude Code, Cursor, Copilot…) | **Mobile MCP** | | Scripting or CI, want raw control | **mobilecli** directly (CLI or JSON-RPC) | | You need real devices at scale | **Mobile Next Cloud** | ## How a single action flows When Mobile MCP receives *"tap the Login button"*, it calls MobileCLI, which asks DeviceKit (running on the device) for the accessibility tree, finds the element, and tells DeviceKit to inject the tap — then the result travels back up the same path. Every layer speaks JSON-RPC, so the identical call works whether the device is on your desk or in the cloud. ## Layers **DeviceKit** — Runs on the device (or simulator host). Exposes a JSON-RPC 2.0 API over WebSocket or HTTP. Handles screen capture, accessibility tree dumps, input injection, app lifecycle. Separate implementations for iOS ([devicekit-ios](https://github.com/mobile-next/devicekit-ios)) and Android ([devicekit-android](https://github.com/mobile-next/devicekit-android)). **MobileCLI** — A single Go binary that connects to DeviceKit and exposes a unified interface across iOS and Android. Serves three interfaces: CLI commands, JSON-RPC over WebSocket, JSON-RPC over HTTP POST. Mobilewright and Mobile MCP both talk to MobileCLI. **Mobilewright** — TypeScript/JS automation framework. Connects to MobileCLI via WebSocket. Provides the Playwright-style API (`getByRole`, `expect`, auto-waiting) on top of MobileCLI's raw JSON-RPC calls. **Mobile MCP** — MCP server that connects to MobileCLI. Makes mobile device control available to any MCP-compatible AI agent (Claude Code, Cursor, VS Code Copilot, etc.) as a set of structured tools. **Mobile Next Cloud** — Manages a fleet of MobileCLI instances running in the cloud (AWS Device Farm). Handles device allocation, session management, test result hosting, and permissions. Exposes a REST API for management, JSON-RPC for device interaction, and its own MCP server for remote access. --- # https://mobilenext.ai/docs/cloud/devices Mobile Next Cloud provisions real devices on demand. These are the models currently available, with the OS versions each one ships with. A device is requested by name, platform and OS version — see [Mobile Next Cloud overview](/cloud/overview). 107 device configurations are available. ## iOS ### iPhone | Device | OS versions | Screen (pt) | | --- | --- | --- | | Apple iPhone Air | 26.3.1 | 420 × 912 | | Apple iPhone 17 Pro Max | 26.3.1 | 440 × 956 | | Apple iPhone 17 Pro | 26.3.1 | 402 × 874 | | Apple iPhone 17 | 26.3.1 | 402 × 874 | | Apple iPhone 16 Pro | 26.0, 18.3.1 | 402 × 874 | | Apple iPhone 16 | 26.0, 18.6.2, 18.0 | 393 × 852 | | Apple iPhone 14 Pro Max | 26.5, 18.6 | 430 × 932 | | Apple iPhone 16 Pro Max | 18.3.1 | 440 × 956 | | Apple iPhone 16 Plus | 18.3.1 | 430 × 932 | | Apple iPhone 16e | 18.3.2 | 390 × 844 | | Apple iPhone 15 Pro Max | 17.3.1 | 430 × 932 | | Apple iPhone 15 Pro | 18.1, 17.3.1 | 393 × 852 | | Apple iPhone 15 Plus | 17.4.1 | 430 × 932 | | Apple iPhone 15 | 18.5, 18.0, 17.2.1 | 393 × 852 | | Apple iPhone 14 Pro | 17.3.1 | 393 × 852 | | Apple iPhone 14 | 18.6.2, 17.6.1 | 390 × 844 | | Apple iPhone 13 Pro Max | 17.3 | 428 × 926 | | Apple iPhone 13 | 18.5, 17.6.1 | 390 × 844 | | Apple iPhone 12 | 18.5, 17.5.1 | 390 × 844 | | Apple iPhone 11 | 18.6.2 | 414 × 896 | ### iPad | Device | OS versions | Screen (pt) | | --- | --- | --- | | Apple iPad Air 11 (2024) | 26.1, 18.3.1 | 820 × 1180 | | Apple iPad mini (2024) | 18.6 | 744 × 1133 | | Apple iPad Air 13 (2025) | 18.4.1 | 1024 × 1366 | | Apple iPad Air 11 (2025) | 18.3.2 | 820 × 1180 | | Apple iPad (2025) | 18.3.2 | 820 × 1180 | | Apple iPad (2022) | 17.3.1 | 820 × 1180 | ## Android ### Phones | Device | OS versions | Screen (pt) | | --- | --- | --- | | Google Pixel 10 Pro XL | 16 | 360 × 801 | | Google Pixel 10 Pro | 16 | 360 × 803 | | Google Pixel 10 | 16 | 360 × 808 | | Google Pixel 9 Pro XL | 17, 15 | 336 × 748 | | Google Pixel 9 Pro | 15 | 320 × 714 | | Google Pixel 9a | 15 | 360 × 808 | | Google Pixel 9 | 16, 15 | 360 × 808 | | Google Pixel 8 Pro | 15, 14 | 336 × 748 | | Google Pixel 8a | 15, 14 | 360 × 800 | | Google Pixel 8 | 15, 14 | 360 × 800 | | Google Pixel 7 Pro | 13 | 360 × 780 | | Google Pixel 7a | 13 | 360 × 800 | | Google Pixel 7 | 14, 13 | 360 × 800 | | Google Pixel 6 Pro (Unlocked) | 12 | 480 × 1040 | | Google Pixel 6 (Unlocked) | 13, 12 | 360 × 800 | | Google Pixel 5a 5G | 12 | 360 × 800 | | Google Pixel 5 (Unlocked) | 12 | 360 × 780 | | Google Pixel 4a | 12 | 360 × 780 | | Google Pixel 3a XL | 12 | 360 × 720 | | Samsung Galaxy S26 Ultra | 16 | 360 × 780 | | Samsung Galaxy S26+ | 16 | 360 × 780 | | Samsung Galaxy S26 | 16 | 360 × 780 | | Samsung Galaxy S25 Ultra | 15 | 480 × 1040 | | Samsung Galaxy S25+ | 15 | 480 × 1040 | | Samsung Galaxy S25 | 16, 15 | 360 × 780 | | Samsung Galaxy S24 Ultra | 14 | 480 × 1040 | | Samsung Galaxy S24+ | 14 | 480 × 1040 | | Samsung Galaxy S24 | 14 | 360 × 780 | | Samsung Galaxy S23 Ultra | 13 | 480 × 1029 | | Samsung Galaxy S23+ | 13 | 360 × 780 | | Samsung Galaxy S23 | 14, 13 | 360 × 780 | | Samsung Galaxy S22 Ultra 5G | 12 | 480 × 1029 | | Samsung Galaxy S22+ 5G | 12 | 360 × 780 | | Samsung Galaxy S22 5G | 13, 12 | 360 × 780 | | Samsung Galaxy S21 Ultra | 12 | 480 × 1067 | | Samsung Galaxy S21 | 12 | 360 × 800 | | Samsung Galaxy S20 (Unlocked) | 13 | 480 × 1067 | | Samsung Galaxy A73 5G | 12 | 360 × 800 | | Samsung Galaxy A56 | 15 | 360 × 780 | | Samsung Galaxy A55 | 14 | 360 × 780 | | Samsung Galaxy A54 | 13 | 360 × 780 | | Samsung Galaxy A53 5G | 12 | 360 × 800 | | Samsung Galaxy A36 | 15 | 360 × 780 | | Samsung Galaxy A35 | 14 | 360 × 780 | | Samsung Galaxy A34 | 13 | 360 × 780 | | Samsung Galaxy A26 | 15 | 360 × 780 | | Samsung Galaxy A25 | 14 | 360 × 780 | | Samsung Galaxy A24 4G | 14 | 360 × 780 | | Samsung Galaxy A16 | 14 | 360 × 780 | | Samsung Galaxy A15 | 14 | 360 × 780 | | Samsung Galaxy A14 5G | 13 | 360 × 803 | | Samsung A51 | 13 | 360 × 800 | ### Tablets | Device | OS versions | Screen (pt) | | --- | --- | --- | | Google Pixel Tablet | 16 | 800 × 1280 | | Samsung Galaxy Tab S11 | 16 | 800 × 1280 | | Samsung Galaxy Tab S9 | 13 | 800 × 1280 | | Samsung Galaxy Tab S8 | 12 | 800 × 1280 | | Samsung Galaxy Tab A9 | 13 | 400 × 670 | | Samsung Galaxy Tab A7 Lite | 13 | 400 × 670 | --- # https://mobilenext.ai/docs/cloud/installation/chatgpt-web-desktop Coming soon. --- # https://mobilenext.ai/docs/cloud/installation/claude-code ```bash claude mcp add mobilenext --transport http https://app.mobilenext.ai/mcp ``` The first time Claude Code uses a Mobile Next tool, your browser opens to authorize your Mobile Next account. To authenticate ahead of time instead, run: ```bash claude mcp login mobilenext ``` Once authenticated, you can start allocating cloud devices. ## Tutorial --- # https://mobilenext.ai/docs/cloud/installation/claude-web-desktop Follow these instructions to connect Mobile Next Cloud MCP to your Claude Web and Claude Desktop. There is nothing to download. 1. In left sidebar, click **"Customize"** ![Step 1](/mobilenext-mcp/claude-web/claude-web-1.png) 2. Select **"Connect your apps"** ![Step 2](/mobilenext-mcp/claude-web/claude-web-2.png) 3. Click on **"Manage connectors"** ![Step 3](/mobilenext-mcp/claude-web/claude-web-3.png) 4. Click on **"Plus**" to add a new connector ![Step 4](/mobilenext-mcp/claude-web/claude-web-4.png) 5. Select **"Add custom connector"** ![Step 5](/mobilenext-mcp/claude-web/claude-web-5.png) 6. Type **"mobilenext"** in name field, and `https://app.mobilenext.ai/mcp` in url, click **"Add"** ![Step 6](/mobilenext-mcp/claude-web/claude-web-6.png) 7. Lastly, click on **"Connect**" to start the authorization flow ![Step 7](/mobilenext-mcp/claude-web/claude-web-7.png) 8. You have successfully connected Claude with Mobile Next Cloud ✅ ![Step 8](/mobilenext-mcp/claude-web/claude-web-8.png) --- # https://mobilenext.ai/docs/cloud/installation/codex ```bash codex mcp add mobilenext --url https://app.mobilenext.ai/mcp ``` Codex will immediately start the authorization flow, approving connection between Codex and Mobile Next. Once approved and done, you are ready to use Mobile Next Cloud. --- # https://mobilenext.ai/docs/cloud/installation/cursor #### Click the button to install: [Install in Cursor](https://cursor.com/en/install-mcp?name=mobilenext&config=eyJ1cmwiOiJodHRwczovL2FwcC5tb2JpbGVuZXh0LmFpL21jcCJ9) #### Or install manually: Go to `Cursor Settings` → `MCP` → `Add new MCP Server`. Name it `mobilenext`, choose the **URL** type, and set the URL to `https://app.mobilenext.ai/mcp`. Cursor will start the authorization flow in your browser. Once you approve, you are ready to use Mobile Next Cloud. --- # https://mobilenext.ai/docs/cloud/installation/gemini-cli ```bash gemini mcp add --transport http --scope user mobilenext https://app.mobilenext.ai/mcp ``` The first time Gemini CLI connects, your browser opens to authorize your Mobile Next account. Once approved, you are ready to use Mobile Next Cloud. --- # https://mobilenext.ai/docs/cloud/introduction `mobilenext` is a **remote MCP server** that gives your AI agent real iOS and Android devices in the cloud. There is nothing to download or run locally — you add one URL to your agent, log in through your browser, and your agent can allocate a device, install your app, and start tapping, typing, and taking screenshots. ![Architecture Diagram](/architecture-diagram.svg) ## Get started in two steps 1. **Add the server to your agent** — pick your client under [Installation](/cloud/installation/claude-code): ```bash claude mcp add mobilenext --transport http https://app.mobilenext.ai/mcp ``` 2. **Ask your agent for a device.** The first tool call opens your browser to authorize your Mobile Next account, then the agent takes it from there: > Allocate an iOS device, install my app, and walk through the login flow. ## What your agent can do - **Allocate and release** real iOS and Android devices on demand - **Install apps** — upload your own `.apk`/`.ipa` (unsigned iOS builds are re-signed automatically) - **Drive the UI** — tap, swipe, type, press buttons, read the accessibility tree - **See the screen** — screenshots, screen recordings, and a live interactive device view See [Tools & Prompts](/cloud/tools-and-prompts) for the full tool reference, including how device allocation and sessions work. ## Core Resources | Resource | Description | |----------|-------------| | [Installation](/cloud/installation/claude-code) | Set up the MCP server in Claude Code, Claude Web/Desktop, Codex, Cursor, or Gemini CLI | | [Using Mobile Next Cloud MCP](/cloud/using-mobilenext-mcp) | How the remote server and authorization work | | [Tools and Prompts](/cloud/tools-and-prompts) | Available tools and prompts for Mobile Next Cloud MCP | --- # https://mobilenext.ai/docs/cloud/overview Mobile Next Cloud is a cloud device farm service that lets you programmatically allocate and release mobile devices on demand. You can perform operations such as installing apps, listing elements on screen, tapping, typing, and more — all without physically connecting a device to your computer. ![Mobile Next Cloud Architecture](/mobile-next-cloud-architecture-placeholder.png) --- # https://mobilenext.ai/docs/cloud/tools-and-prompts Available tools and prompts for Mobile Next Cloud MCP Server. ## Tools | Tool | Description | |------|-------------| | `mobilenext_list_available_devices` | List your allocated devices and devices available for allocation | | `mobilenext_allocate_device` | Reserve a device from the remote fleet for testing and development. Allocation is asynchronous — see [How allocation works](#how-allocation-works) | | `mobilenext_release_device` | Release a device back to the remote fleet | | `mobilenext_list_apps` | List all the installed apps on the device | | `mobilenext_launch_app` | Launch an app on mobile device | | `mobilenext_terminate_app` | Stop and terminate an app on mobile device | | `mobilenext_create_upload` | Create a presigned upload URL. `PUT` your `.apk`/`.ipa` file to the returned URL, then pass the `uploadId` to `mobilenext_install_app` | | `mobilenext_install_app` | Install an app on a device — pass an `uploadId` from `mobilenext_create_upload`, or a URL to a `.apk`/`.ipa` file hosted at `github.com/mobile-next` | | `mobilenext_get_screen_size` | Get the screen size of the mobile device in pixels | | `mobilenext_click_on_screen_at_coordinates` | Click on the screen at given x,y coordinates | | `mobilenext_double_tap_on_screen` | Double-tap on the screen at given x,y coordinates | | `mobilenext_long_press_on_screen_at_coordinates` | Long press on the screen at given x,y coordinates | | `mobilenext_list_elements_on_screen` | List elements on screen and their coordinates, with display text or accessibility label | | `mobilenext_press_button` | Press a device button: `HOME`, `BACK` (Android only), `VOLUME_UP`, `VOLUME_DOWN`, `ENTER`, or a D-pad button | | `mobilenext_open_url` | Open a URL in browser on device | | `mobilenext_swipe_on_screen` | Swipe on the screen | | `mobilenext_type_keys` | Type text into the focused element | | `mobilenext_take_screenshot` | Take a screenshot of the mobile device. | | `mobilenext_save_screenshot` | Take a screenshot of the mobile device and return a download URL | | `mobilenext_set_orientation` | Change the screen orientation of the device | | `mobilenext_get_orientation` | Get the current screen orientation of the device | | `mobilenext_start_screen_recording` | Start recording the screen of a mobile device | | `mobilenext_stop_screen_recording` | Stop an active screen recording on a mobile device | ## How allocation works Device allocation is asynchronous. When `mobilenext_allocate_device` returns a device in the `allocating` state, provisioning is still in progress — Android devices are typically ready within a minute, while iOS devices can take a few minutes. Your agent can check progress by calling `mobilenext_list_available_devices` again; there is no need to re-allocate. Allocating a device creates a session (or joins the session ID you pass in). Keep the returned session ID — `mobilenext_release_device` needs it to release the device when you're done. ## Installing your own app To test your own build, upload it first: call `mobilenext_create_upload`, `PUT` the file to the returned presigned URL, then call `mobilenext_install_app` with the `uploadId`. For iOS, IPA files may be **unsigned or ad hoc signed** — Mobile Next Cloud re-signs them automatically before installation, so you don't need a device-provisioned signing profile. Direct-URL installs are limited to `.apk`/`.ipa` files hosted at `github.com/mobile-next` (such as the Milliways sample app); use the upload flow for everything else. --- # https://mobilenext.ai/docs/cloud/using-mobilenext-mcp `mobilenext` is a remote MCP server that requires no downloads or local installation. It allows you to control your cloud devices directly through your AI agent — allocate devices, install apps, interact with UI elements, and more, all from your agent's conversation. When adding the MCP server, you will be redirected to authorize your Mobile Next account. --- # https://mobilenext.ai/docs/guides/claude-code-real-phone ## Prerequisites A booted iOS simulator or Android emulator (or connected real device). Node.js v22+. - iOS: `xcrun simctl boot "iPhone 16"` to start a simulator - Android: start an emulator via Android Studio or `emulator -avd ` ## 1. Add Mobile MCP to Claude Code ```bash claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest ``` ## 2. Verify the connection In Claude Code, type `/mcp`. You should see `mobile-mcp` listed and connected. ## 3. Ask Claude to interact with your device Some example prompts: - "List the devices available and take a screenshot of the current screen" - "Open the Settings app and navigate to Wi-Fi settings" - "Launch com.example.myapp, sign in with email user@example.com and password test123" - "Take a screenshot, describe what's on screen, then tap the first button you see" ## 4. Install and test an app ``` Install the app at /path/to/MyApp.ipa, launch it, and tell me what you see on the home screen. ``` ## Troubleshooting - If no devices appear: confirm your simulator/emulator is booted (`xcrun simctl list` or `adb devices`) - If Mobile MCP disconnects: restart Claude Code and reconnect via `/mcp` ## Next steps [Mobile MCP on GitHub](https://github.com/mobile-next/mobile-mcp) | [Mobile Next Cloud](/cloud/overview/) (for cloud devices) --- # https://mobilenext.ai/docs/guides/mobile-tests-in-ci This guide shows how to run Mobilewright tests against an iOS simulator in GitHub Actions. Android CI setup follows the same pattern with Android-specific setup steps. **Prerequisites:** Mobilewright tests already running locally (see [Test an iOS App with Mobilewright](/guides/test-ios-app-with-mobilewright/)). ## GitHub Actions workflow Create `.github/workflows/mobile-tests.yml`: ```yaml name: Mobile Tests on: push: branches: [main] pull_request: jobs: test: runs-on: macos-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '22' - name: Install dependencies run: npm ci - name: Boot simulator run: | xcrun simctl boot "iPhone 16" || true xcrun simctl bootstatus "iPhone 16" -b - name: Run Mobilewright tests run: npx mobilewright test --reporter list - name: Upload test report if: always() uses: actions/upload-artifact@v4 with: name: mobilewright-report path: mobilewright-report/ ``` ## Android CI Swap the simulator setup step with: ```yaml - name: Start Android emulator uses: reactivecircus/android-emulator-runner@v2 with: api-level: 35 script: npx mobilewright test --reporter list ``` ## Cloud devices Running on macOS GitHub Actions runners is slower and more expensive than running against cloud devices. With [Mobile Next Cloud](/cloud/overview/), your tests run on managed real devices and your CI can use a standard `ubuntu-latest` runner. See [Mobile Next Cloud](/cloud/overview/) for setup. --- # https://mobilenext.ai/docs/guides/test-ios-app-with-mobilewright ## Prerequisites Node.js >= 18, Xcode with Command Line Tools, and a booted iPhone simulator or connected real device. ## 1. Install Mobilewright ```bash npm install mobilewright @mobilewright/test ``` ## 2. Verify your environment ```bash npx mobilewright doctor npx mobilewright devices # confirm your device appears ``` ## 3. Initialize project config ```bash npx mobilewright init ``` This creates `mobilewright.config.ts` and an example test file. ## 4. Edit `mobilewright.config.ts` Set your app's bundle ID: ```typescript import { defineConfig } from 'mobilewright'; export default defineConfig({ platform: 'ios', bundleId: 'com.example.myapp', timeout: 10_000, }); ``` ## 5. Write a test In `example.test.ts`: ```typescript import { test, expect } from '@mobilewright/test'; test('can sign in', async ({ device, screen, bundleId }) => { await device.terminateApp(bundleId).catch(() => {}); await device.launchApp(bundleId); await screen.getByLabel('Email').fill('user@example.com'); await screen.getByLabel('Password').fill('password123'); await screen.getByRole('button', { name: 'Sign In' }).tap(); await expect(screen.getByText('Welcome back')).toBeVisible(); }); ``` ## 6. Run the tests ```bash npx mobilewright test ``` Optional flags: ```bash npx mobilewright test --reporter html # generate HTML report npx mobilewright test --retries 2 # retry flaky tests npx mobilewright show-report # open HTML report ``` ## Test failures When a test fails, Mobilewright automatically takes a screenshot at the point of failure and attaches it to the report. ## Next steps [Mobilewright Overview](/mobilewright/overview/) | [Mobile Next Cloud](/cloud/overview/) --- # https://mobilenext.ai/docs # The mobile automation layer for AI agents and developers Control any iOS or Android device — real or virtual, local or cloud — from code, the CLI, or your AI agent. ## What do you want to do? Write end-to-end tests with **Mobilewright**, a Playwright-style automation framework for iOS and Android. Hand a local device to any AI agent with **Mobile MCP** — open source, no cloud account needed. Use **MobileCLI**, one Go binary that replaces `simctl`, `adb`, and `go-ios`. Allocate real iOS and Android devices on demand with **Mobile Next Cloud** — no hardware setup. ## The products **MobileCLI** — One Go binary that replaces `simctl`, `adb`, and `go-ios`. Supports CLI, JSON-RPC over WebSocket, and JSON-RPC over HTTP. [Get started](https://github.com/mobile-next/mobilecli) **Mobilewright** — TypeScript/JavaScript automation framework for iOS and Android, built upon Playwright. Auto-waiting, semantic locators, cross-platform. Works locally and with cloud devices. [Get started](/mobilewright/overview) **Mobile MCP** — Open-source MCP server that gives AI agents direct control of local iOS and Android devices. No cloud account needed. [Get started](https://github.com/mobile-next/mobile-mcp) **Mobile Next Cloud** — Cloud device farm. Allocate real iOS and Android devices on demand. No hardware setup. Accessible via MCP, REST API, or the web dashboard at app.mobilenext.ai. [Get started](/cloud/overview) :::tip For AI agents Use [llms.txt](pathname:///docs/llms.txt) for the documentation index and [llms-full.txt](pathname:///docs/llms-full.txt) for the full text in one file. Append `.md` to any page URL to get its raw markdown. ::: --- # https://mobilenext.ai/docs/mobilewright/overview [Mobilewright](https://mobilewright.dev) is a TypeScript/JavaScript automation framework for iOS and Android, inspired by Playwright's architecture and API. Full documentation is at [mobilewright.dev/docs](https://mobilewright.dev/docs). This page covers how to connect Mobilewright to **Mobile Next Cloud** to run your scripts and tests against real cloud devices instead of local simulators. ## Connect to Mobile Next Cloud Mobilewright uses a `driver` config option to target cloud devices. When `MOBILENEXT_API_KEY` is set, add a `driver` block to your `mobilewright.config.ts`: ```typescript import { defineConfig, type MobilewrightConfig } from 'mobilewright'; const config: MobilewrightConfig = { platform: 'ios', bundleId: 'com.example.myapp', // ...rest of your config }; if (process.env['MOBILENEXT_API_KEY']) { config.driver = { type: 'mobilenext', apiKey: process.env['MOBILENEXT_API_KEY'], }; } export default defineConfig(config); ``` When `MOBILENEXT_API_KEY` is not set, Mobilewright falls back to a local device via mobilecli. This lets you run the same config locally and in CI without any code changes. ## Test result metadata The driver config accepts an optional `testResult` block to label runs in the Mobile Next Cloud dashboard: ```typescript config.driver = { type: 'mobilenext', apiKey: process.env['MOBILENEXT_API_KEY'], testResult: { name: 'Smoke suite', tags: ['nightly'], environment: 'production', }, }; ``` ## Get an API key Get your API key at [app.mobilenext.ai](https://app.mobilenext.ai). See [Mobile Next Cloud](/cloud/overview/) for device allocation and account setup.