user¶

The current Android user on a connected device — relevant on multi-user devices (work profiles, guest users, Android Automotive).

`adb_automation_mcp.modules.user.tools` ¶

Module-level, statically-introspectable tool functions for the user module.

Kept as plain top-level functions, never closures, so that documentation tooling and the registry meta-test can both introspect them directly.

`create_user(ctx: Context, serial: str, name: str) -> CreateUserResult` `async` ¶

Create a full secondary Android user on a device: adb shell pm create-user NAME.

Creates the user only — it does not switch to it (use switch_user separately if that's the goal). name is shell-quoted before being sent to the device, verified live to handle spaces and shell metacharacters safely.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`name`	`str`	Display name for the new user. Can contain spaces.	required

Returns:

Type	Description
`CreateUserResult`	The serial, the newly assigned user_id, and the name requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. Only the unreachable-serial failure path was verified live for this specific command — other real failure modes (e.g. a device's max-user-count limit) haven't been triggered and observed, so they'll surface as a generic backend error rather than a more specific one.

Example

Called with serial="emulator-5554", name="Guest". A typical response:

{
  "status": "success",
  "message": "Created user 12 (Guest) on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 12, "name": "Guest"},
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("write")
async def create_user(ctx: Context, serial: str, name: str) -> CreateUserResult:
    """Create a full secondary Android user on a device: `adb shell pm create-user NAME`.

    Creates the user only — it does not switch to it (use switch_user
    separately if that's the goal). name is shell-quoted before being sent to
    the device, verified live to handle spaces and shell metacharacters
    safely.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        name: Display name for the new user. Can contain spaces.

    Returns:
        The serial, the newly assigned user_id, and the name requested.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the
        serial doesn't match a connected device, that surfaces as an actual
        tool error. Only the unreachable-serial failure path was verified
        live for this specific command — other real failure modes (e.g. a
        device's max-user-count limit) haven't been triggered and observed,
        so they'll surface as a generic backend error rather than a more
        specific one.

    Example:
        Called with serial="emulator-5554", name="Guest". A typical response:

        ```json
        {
          "status": "success",
          "message": "Created user 12 (Guest) on emulator-5554.",
          "data": {"serial": "emulator-5554", "user_id": 12, "name": "Guest"},
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.create_user(serial, name)

`dump_user(ctx: Context, serial: str) -> UserDump` `async` ¶

Dump detailed Android user info for a device: adb shell dumpsys user.

UserManagerService's diagnostic dump — every user's state, flags, restrictions, and running/locked status — far more detail than get_current_user's bare user ID. No userId argument: verified live that dumpsys user's optional userId has no effect at all (dumpsys user 0, dumpsys user 10, and dumpsys user 9999 all produced identical output) — it always dumps every user on the device, so there's nothing to pass. For detail on just one specific user, use user_info instead.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`UserDump`	The raw dumpsys text output, plus the serial requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Dumped users on emulator-5554 (23000 chars).",
  "data": {
    "serial": "emulator-5554",
    "output": "Current user: 10\n\nUsers:\n  UserInfo{0:null:811} ..."
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def dump_user(ctx: Context, serial: str) -> UserDump:
    """Dump detailed Android user info for a device: `adb shell dumpsys user`.

    UserManagerService's diagnostic dump — every user's state, flags,
    restrictions, and running/locked status — far more detail than
    get_current_user's bare user ID. No userId argument: verified live that
    `dumpsys user`'s optional userId has no effect at all (`dumpsys user 0`,
    `dumpsys user 10`, and `dumpsys user 9999` all produced identical output)
    — it always dumps every user on the device, so there's nothing to pass.
    For detail on just one specific user, use user_info instead.

    Args:
        serial: The target device's adb serial (see list_connected_devices).

    Returns:
        The raw dumpsys text output, plus the serial requested.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the serial
        doesn't match a connected device, that surfaces as an actual tool
        error.

    Example:
        Called with serial="emulator-5554". A typical response:

        ```json
        {
          "status": "success",
          "message": "Dumped users on emulator-5554 (23000 chars).",
          "data": {
            "serial": "emulator-5554",
            "output": "Current user: 10\\n\\nUsers:\\n  UserInfo{0:null:811} ..."
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.dump_user(serial)

`get_current_user(ctx: Context, serial: str) -> CurrentUser` `async` ¶

Get the current Android user on a device: adb shell am get-current-user.

Relevant on multi-user devices (work profiles, guest users, Android Automotive) where more than one user account can exist; most single-user devices just report user 0 (the primary/owner user).

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`CurrentUser`	The device's serial and its current Android user ID.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Current user on emulator-5554 is 0.",
  "data": {"serial": "emulator-5554", "user_id": 0},
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def get_current_user(ctx: Context, serial: str) -> CurrentUser:
    """Get the current Android user on a device: `adb shell am get-current-user`.

    Relevant on multi-user devices (work profiles, guest users, Android
    Automotive) where more than one user account can exist; most single-user
    devices just report user 0 (the primary/owner user).

    Args:
        serial: The target device's adb serial (see list_connected_devices).

    Returns:
        The device's serial and its current Android user ID.

    Example:
        Called with serial="emulator-5554". A typical response:

        ```json
        {
          "status": "success",
          "message": "Current user on emulator-5554 is 0.",
          "data": {"serial": "emulator-5554", "user_id": 0},
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.get_current_user(serial)

`get_user_capabilities(ctx: Context, serial: str) -> UserCapabilities` `async` ¶

Get device-wide Android multi-user capabilities: what the platform build supports, not info about any one particular user.

Aggregates several underlying commands (pm supports-multiple-users, pm get-max-users, pm get-max-running-users, cmd user is-headless-system-user-mode, cmd user is-visible-background-users-supported, cmd user is-visible-background-users-on-default-display-supported) into one flat result — callers never need to know which underlying command family answers a given question. For detail on a specific existing user, use user_info, dump_user, or list_users instead.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type Description

UserCapabilities

The device's serial plus its multi-user support flags/limits. The three pm-backed fields (supports_multiple_users, max_users, max_running_users) are always populated on any adb-reachable device — multi-user support has existed since Android 4.2. The three cmd user-backed fields (headless_system_user_mode, visible_background_users_supported, visible_background_users_on_default_display_supported) are newer subcommands not available on every Android version; each is independently None when unsupported on this particular device rather than failing the whole call.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error for any of the six underlying commands. A non-zero exit from one of the three newer cmd user subcommands that is NOT a device/serial problem (e.g. an unrecognized subcommand on an older Android build) is not treated as an error — it degrades just that one field to None and the call still returns the rest of the data successfully. Unparseable output from one of the three older, stable pm commands is treated as a genuine unexpected-shape failure rather than a version-gating issue, since those commands have been stable since Android 4.2.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "emulator-5554 supports multiple users (max 4, max running 4).",
  "data": {
    "serial": "emulator-5554",
    "supports_multiple_users": true,
    "max_users": 4,
    "max_running_users": 4,
    "headless_system_user_mode": false,
    "visible_background_users_supported": false,
    "visible_background_users_on_default_display_supported": false
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def get_user_capabilities(ctx: Context, serial: str) -> UserCapabilities:
    """Get device-wide Android multi-user capabilities: what the platform
    build supports, not info about any one particular user.

    Aggregates several underlying commands (`pm supports-multiple-users`, `pm
    get-max-users`, `pm get-max-running-users`, `cmd user
    is-headless-system-user-mode`, `cmd user
    is-visible-background-users-supported`, `cmd user
    is-visible-background-users-on-default-display-supported`) into one flat
    result — callers never need to know which underlying command family
    answers a given question. For detail on a specific existing user, use
    user_info, dump_user, or list_users instead.

    Args:
        serial: The target device's adb serial (see list_connected_devices).

    Returns:
        The device's serial plus its multi-user support flags/limits. The
        three `pm`-backed fields (supports_multiple_users, max_users,
        max_running_users) are always populated on any adb-reachable device —
        multi-user support has existed since Android 4.2. The three `cmd
        user`-backed fields (headless_system_user_mode,
        visible_background_users_supported,
        visible_background_users_on_default_display_supported) are newer
        subcommands not available on every Android version; each is
        independently None when unsupported on this particular device rather
        than failing the whole call.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the
        serial doesn't match a connected device, that surfaces as an actual
        tool error for any of the six underlying commands. A non-zero exit
        from one of the three newer `cmd user` subcommands that is NOT a
        device/serial problem (e.g. an unrecognized subcommand on an older
        Android build) is not treated as an error — it degrades just that one
        field to None and the call still returns the rest of the data
        successfully. Unparseable output from one of the three older, stable
        `pm` commands is treated as a genuine unexpected-shape failure rather
        than a version-gating issue, since those commands have been stable
        since Android 4.2.

    Example:
        Called with serial="emulator-5554". A typical response:

        ```json
        {
          "status": "success",
          "message": "emulator-5554 supports multiple users (max 4, max running 4).",
          "data": {
            "serial": "emulator-5554",
            "supports_multiple_users": true,
            "max_users": 4,
            "max_running_users": 4,
            "headless_system_user_mode": false,
            "visible_background_users_supported": false,
            "visible_background_users_on_default_display_supported": false
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.get_user_capabilities(serial)

`get_user_state(ctx: Context, serial: str, user_id: int) -> UserRunState` `async` ¶

Get a started user's lifecycle state: adb shell am get-started-user-state.

Reports where a started user is in the ActivityManager lifecycle (BOOTING → RUNNING_LOCKED → RUNNING_UNLOCKING → RUNNING_UNLOCKED → STOPPING → SHUTDOWN) — useful for waiting until a user reaches RUNNING_UNLOCKED before launching activities under it. A user that isn't currently started reports started=false, not an error.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to inspect (see list_users).	required

Returns:

Type	Description
`UserRunState`	The serial, user_id, started (false when the user isn't running), and state — the raw lifecycle token when started, otherwise null.

Error handling

A negative user_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Empty output raises BACKEND_ERROR; the "User is not started" message is a normal started=false result, not a failure.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 on emulator-5554: RUNNING_UNLOCKED.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "started": true,
    "state": "RUNNING_UNLOCKED"
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def get_user_state(ctx: Context, serial: str, user_id: int) -> UserRunState:
    """Get a started user's lifecycle state: `adb shell am get-started-user-state`.

    Reports where a started user is in the ActivityManager lifecycle
    (BOOTING → RUNNING_LOCKED → RUNNING_UNLOCKING → RUNNING_UNLOCKED →
    STOPPING → SHUTDOWN) — useful for waiting until a user reaches
    RUNNING_UNLOCKED before launching activities under it. A user that isn't
    currently started reports started=false, not an error.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user id to inspect (see list_users).

    Returns:
        The serial, user_id, started (false when the user isn't running),
        and state — the raw lifecycle token when started, otherwise null.

    Error handling:
        A negative user_id raises INVALID_ARGUMENT before anything runs. An
        unknown serial or unresponsive adb binary raises
        DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Empty output raises BACKEND_ERROR;
        the "User is not started" message is a normal started=false result,
        not a failure.

    Example:
        Called with serial="emulator-5554", user_id=10. A typical response:

        ```json
        {
          "status": "success",
          "message": "User 10 on emulator-5554: RUNNING_UNLOCKED.",
          "data": {
            "serial": "emulator-5554",
            "user_id": 10,
            "started": true,
            "state": "RUNNING_UNLOCKED"
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.get_user_state(serial, user_id)

`is_user_stopped(ctx: Context, serial: str, user_id: int) -> UserStoppedState` `async` ¶

Check whether an Android user is stopped: adb shell am is-user-stopped.

A quick boolean gate before user-scoped automation — if a user is stopped, start_user it first. This does not distinguish "stopped" from "no such user"; both report stopped=true.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to check (see list_users).	required

Returns:

Type	Description
`UserStoppedState`	The serial, user_id, and stopped (true when the user is in the stopped state or does not exist).

Error handling

A negative user_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Output that is neither "true" nor "false" raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 on emulator-5554 is not stopped.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "stopped": false
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def is_user_stopped(ctx: Context, serial: str, user_id: int) -> UserStoppedState:
    """Check whether an Android user is stopped: `adb shell am is-user-stopped`.

    A quick boolean gate before user-scoped automation — if a user is
    stopped, start_user it first. This does not distinguish "stopped" from
    "no such user"; both report stopped=true.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user id to check (see list_users).

    Returns:
        The serial, user_id, and stopped (true when the user is in the
        stopped state or does not exist).

    Error handling:
        A negative user_id raises INVALID_ARGUMENT before anything runs. An
        unknown serial or unresponsive adb binary raises
        DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Output that is neither "true" nor
        "false" raises BACKEND_ERROR.

    Example:
        Called with serial="emulator-5554", user_id=10. A typical response:

        ```json
        {
          "status": "success",
          "message": "User 10 on emulator-5554 is not stopped.",
          "data": {
            "serial": "emulator-5554",
            "user_id": 10,
            "stopped": false
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.is_user_stopped(serial, user_id)

`list_users(ctx: Context, serial: str) -> UserList` `async` ¶

List every Android user on a device: adb shell cmd user list -v.

Structured, one entry per user (id, name, type, flags, and states like "running"/"current"/"visible") — the fastest way to see what user IDs actually exist before calling user_info or switch_user with one.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`UserList`	The device's serial and every user currently defined on it.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "2 users on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "users": [
      {
        "user_id": 0,
        "name": "System User",
        "type": "system.HEADLESS",
        "flags": ["INITIALIZED", "PRIMARY", "SYSTEM"],
        "states": ["running"]
      },
      {
        "user_id": 10,
        "name": "Driver",
        "type": "full.SECONDARY",
        "flags": ["ADMIN", "FULL", "INITIALIZED"],
        "states": ["running", "current", "visible"]
      }
    ]
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def list_users(ctx: Context, serial: str) -> UserList:
    """List every Android user on a device: `adb shell cmd user list -v`.

    Structured, one entry per user (id, name, type, flags, and states like
    "running"/"current"/"visible") — the fastest way to see what user IDs
    actually exist before calling user_info or switch_user with one.

    Args:
        serial: The target device's adb serial (see list_connected_devices).

    Returns:
        The device's serial and every user currently defined on it.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the
        serial doesn't match a connected device, that surfaces as an actual
        tool error.

    Example:
        Called with serial="emulator-5554". A typical response:

        ```json
        {
          "status": "success",
          "message": "2 users on emulator-5554.",
          "data": {
            "serial": "emulator-5554",
            "users": [
              {
                "user_id": 0,
                "name": "System User",
                "type": "system.HEADLESS",
                "flags": ["INITIALIZED", "PRIMARY", "SYSTEM"],
                "states": ["running"]
              },
              {
                "user_id": 10,
                "name": "Driver",
                "type": "full.SECONDARY",
                "flags": ["ADMIN", "FULL", "INITIALIZED"],
                "states": ["running", "current", "visible"]
              }
            ]
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.list_users(serial)

`remove_user(ctx: Context, serial: str, user_id: int) -> RemoveUserResult` `async` ¶

Delete an Android user/profile from a device: adb shell pm remove-user ID.

Irreversibly deletes the user and all of its data — destructive, and denied by policy unless the server is explicitly configured with ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1. Verified live that this also fails (not just for a nonexistent user) if user_id is the device's current/foreground user — switch_user away from it first.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to remove (see list_users).	required

Returns:

Type	Description
`RemoveUserResult`	The serial and user_id removed.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. Verified live that removal failure — whether user_id doesn't exist or is currently active — always reads "Error: couldn't remove user id ", exit code 1; adb doesn't distinguish the two reasons in the message, so neither does this tool.

Example

Called with serial="emulator-5554", user_id=12. A typical response:

{
  "status": "success",
  "message": "Removed user 12 on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 12},
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("destructive")
async def remove_user(ctx: Context, serial: str, user_id: int) -> RemoveUserResult:
    """Delete an Android user/profile from a device: `adb shell pm remove-user ID`.

    Irreversibly deletes the user and all of its data — destructive, and
    denied by policy unless the server is explicitly configured with
    ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1. Verified live that this also fails (not just
    for a nonexistent user) if user_id is the device's current/foreground
    user — switch_user away from it first.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user ID to remove (see list_users).

    Returns:
        The serial and user_id removed.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the
        serial doesn't match a connected device, that surfaces as an actual
        tool error. Verified live that removal failure — whether user_id
        doesn't exist or is currently active — always reads "Error: couldn't
        remove user id <id>", exit code 1; adb doesn't distinguish the two
        reasons in the message, so neither does this tool.

    Example:
        Called with serial="emulator-5554", user_id=12. A typical response:

        ```json
        {
          "status": "success",
          "message": "Removed user 12 on emulator-5554.",
          "data": {"serial": "emulator-5554", "user_id": 12},
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.remove_user(serial, user_id)

`start_user(ctx: Context, serial: str, user_id: int, wait: bool = False, display_id: int | None = None) -> StartUserResult` `async` ¶

Start a stopped Android user in the background: adb shell am start-user.

Brings a stopped secondary user (a work profile, guest, or Automotive passenger user) to the RUNNING state without switching the foreground to it — use switch_user for a foreground switch. Starting an already-running user is a harmless success. To bring one to the foreground on a specific screen, pass display_id (only meaningful on builds that support visible background users, typically automotive).

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to start (see list_users).	required
`wait`	`bool`	When true, pass `-w` so the call blocks until the user is fully started and unlocked before returning.	`False`
`display_id`	`int \| None`	Make the user visible on this logical display so it can launch activities there (`--display`). Omit for a plain background start. Unsupported on most non-automotive builds.	`None`

Returns:

Type	Description
`StartUserResult`	The serial, user_id, the wait and display_id that were requested, started (always true when this returns without error), and the raw `am` message ("Success: user started").

Error handling

A negative user_id or display_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. am start-user exits 0 even when it fails, so a non-"Success" message ("Error: could not start user", or a build rejecting --display) raises BACKEND_ERROR carrying that message.

Example

Called with serial="emulator-5554", user_id=10, wait=true. A typical response:

{
  "status": "success",
  "message": "Started user 10 on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "wait": true,
    "display_id": null,
    "started": true,
    "output": "Success: user started"
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("write")
async def start_user(
    ctx: Context,
    serial: str,
    user_id: int,
    wait: bool = False,
    display_id: int | None = None,
) -> StartUserResult:
    """Start a stopped Android user in the background: `adb shell am start-user`.

    Brings a stopped secondary user (a work profile, guest, or Automotive
    passenger user) to the RUNNING state without switching the foreground to
    it — use switch_user for a foreground switch. Starting an
    already-running user is a harmless success. To bring one to the
    foreground on a specific screen, pass display_id (only meaningful on
    builds that support visible background users, typically automotive).

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user id to start (see list_users).
        wait: When true, pass `-w` so the call blocks until the user is
            fully started and unlocked before returning.
        display_id: Make the user visible on this logical display so it can
            launch activities there (`--display`). Omit for a plain
            background start. Unsupported on most non-automotive builds.

    Returns:
        The serial, user_id, the wait and display_id that were requested,
        started (always true when this returns without error), and the raw
        `am` message ("Success: user started").

    Error handling:
        A negative user_id or display_id raises INVALID_ARGUMENT before
        anything runs. An unknown serial or unresponsive adb binary raises
        DEVICE_NOT_FOUND/ADB_UNAVAILABLE. `am start-user` exits 0 even when
        it fails, so a non-"Success" message ("Error: could not start user",
        or a build rejecting `--display`) raises BACKEND_ERROR carrying that
        message.

    Example:
        Called with serial="emulator-5554", user_id=10, wait=true. A typical
        response:

        ```json
        {
          "status": "success",
          "message": "Started user 10 on emulator-5554.",
          "data": {
            "serial": "emulator-5554",
            "user_id": 10,
            "wait": true,
            "display_id": null,
            "started": true,
            "output": "Success: user started"
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.start_user(serial, user_id, wait=wait, display_id=display_id)

`switch_user(ctx: Context, serial: str, user_id: int) -> SwitchUserResult` `async` ¶

Switch the active Android user on a device: adb shell am switch-user ID.

Changes what's actually running in the foreground on the device — not a read, and not safely re-invocable without consequence (it interrupts whatever the current user was doing). Use list_users first to find a valid target user ID.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to switch to (see list_users).	required

Returns:

Type	Description
`SwitchUserResult`	The serial and user_id switched to. Only returned on success — see Error handling below.

Error handling

Unlike connect_device, am switch-user's exit code was verified live to be reliable, so failure is a real tool error, not success:false data: an invalid user_id fails with "Error: Failed to switch to user ", exit code 1 — same as an unreachable serial or an unresponsive adb binary.

Example

Called with serial="emulator-5554", user_id=0. A typical response:

{
  "status": "success",
  "message": "Switched to user 0 on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 0},
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("write")
async def switch_user(ctx: Context, serial: str, user_id: int) -> SwitchUserResult:
    """Switch the active Android user on a device: `adb shell am switch-user ID`.

    Changes what's actually running in the foreground on the device — not a
    read, and not safely re-invocable without consequence (it interrupts
    whatever the current user was doing). Use list_users first to find a
    valid target user ID.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user ID to switch to (see list_users).

    Returns:
        The serial and user_id switched to. Only returned on success —
        see Error handling below.

    Error handling:
        Unlike connect_device, `am switch-user`'s exit code was verified live
        to be reliable, so failure is a real tool error, not success:false
        data: an invalid user_id fails with "Error: Failed to switch to user
        <id>", exit code 1 — same as an unreachable serial or an unresponsive
        adb binary.

    Example:
        Called with serial="emulator-5554", user_id=0. A typical response:

        ```json
        {
          "status": "success",
          "message": "Switched to user 0 on emulator-5554.",
          "data": {"serial": "emulator-5554", "user_id": 0},
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.switch_user(serial, user_id)

`user_info(ctx: Context, serial: str, user_id: int) -> UserInfo` `async` ¶

Get detailed info for one Android user: adb shell dumpsys user --user ID.

Unlike dump_user's plain dumpsys user (which always dumps every user and ignores any ID you give it), --user genuinely filters — verified live that --user 0 and --user 10 return different, single-user blocks. Use this when you want just one user's detail; use dump_user for every user at once.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to look up (see list_users to find valid IDs on this device).	required

Returns:

Type	Description
`UserInfo`	The requested user's raw dumpsys block, plus the serial and user_id requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. A user_id that doesn't exist on an otherwise-reachable device is also an error (not success:false data) — verified live that adb reports this as ordinary stdout ("User not found") with exit code 0, so this tool detects that text and raises rather than returning it as if it were real user data.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 info on emulator-5554 (850 chars).",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "output": "UserInfo{10:Driver:412} serialNo=10 isPrimary=false\n..."
  },
  "error": null
}

Source code in src/adb_automation_mcp/modules/user/tools.py

@category("read")
async def user_info(ctx: Context, serial: str, user_id: int) -> UserInfo:
    """Get detailed info for one Android user: `adb shell dumpsys user --user ID`.

    Unlike dump_user's plain `dumpsys user` (which always dumps every user
    and ignores any ID you give it), `--user` genuinely filters — verified
    live that `--user 0` and `--user 10` return different, single-user
    blocks. Use this when you want just one user's detail; use dump_user for
    every user at once.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        user_id: The Android user ID to look up (see list_users to find valid
            IDs on this device).

    Returns:
        The requested user's raw dumpsys block, plus the serial and user_id
        requested.

    Error handling:
        Propagates the same way most tools do (unlike check_adb_available): if
        the adb binary itself can't be found or is unresponsive, or the
        serial doesn't match a connected device, that surfaces as an actual
        tool error. A user_id that doesn't exist on an otherwise-reachable
        device is also an error (not success:false data) — verified live that
        adb reports this as ordinary stdout ("User <id> not found") with exit
        code 0, so this tool detects that text and raises rather than
        returning it as if it were real user data.

    Example:
        Called with serial="emulator-5554", user_id=10. A typical response:

        ```json
        {
          "status": "success",
          "message": "User 10 info on emulator-5554 (850 chars).",
          "data": {
            "serial": "emulator-5554",
            "user_id": 10,
            "output": "UserInfo{10:Driver:412} serialNo=10 isPrimary=false\\n..."
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    user = cast(UserService, services["user"])
    return await user.user_info(serial, user_id)

user¶

adb_automation_mcp.modules.user.tools ¶

create_user(ctx: Context, serial: str, name: str) -> CreateUserResult async ¶

dump_user(ctx: Context, serial: str) -> UserDump async ¶

get_current_user(ctx: Context, serial: str) -> CurrentUser async ¶

get_user_capabilities(ctx: Context, serial: str) -> UserCapabilities async ¶

get_user_state(ctx: Context, serial: str, user_id: int) -> UserRunState async ¶

is_user_stopped(ctx: Context, serial: str, user_id: int) -> UserStoppedState async ¶

list_users(ctx: Context, serial: str) -> UserList async ¶

remove_user(ctx: Context, serial: str, user_id: int) -> RemoveUserResult async ¶

start_user(ctx: Context, serial: str, user_id: int, wait: bool = False, display_id: int | None = None) -> StartUserResult async ¶

switch_user(ctx: Context, serial: str, user_id: int) -> SwitchUserResult async ¶

user_info(ctx: Context, serial: str, user_id: int) -> UserInfo async ¶

`adb_automation_mcp.modules.user.tools` ¶

`create_user(ctx: Context, serial: str, name: str) -> CreateUserResult` `async` ¶

`dump_user(ctx: Context, serial: str) -> UserDump` `async` ¶

`get_current_user(ctx: Context, serial: str) -> CurrentUser` `async` ¶

`get_user_capabilities(ctx: Context, serial: str) -> UserCapabilities` `async` ¶

`get_user_state(ctx: Context, serial: str, user_id: int) -> UserRunState` `async` ¶

`is_user_stopped(ctx: Context, serial: str, user_id: int) -> UserStoppedState` `async` ¶

`list_users(ctx: Context, serial: str) -> UserList` `async` ¶

`remove_user(ctx: Context, serial: str, user_id: int) -> RemoveUserResult` `async` ¶

`start_user(ctx: Context, serial: str, user_id: int, wait: bool = False, display_id: int | None = None) -> StartUserResult` `async` ¶

`switch_user(ctx: Context, serial: str, user_id: int) -> SwitchUserResult` `async` ¶

`user_info(ctx: Context, serial: str, user_id: int) -> UserInfo` `async` ¶