Skip to content

settings

Reading and writing Android Settings provider values (adb shell settings get/put NAMESPACE KEY) — distinct from the system_properties module's getprop/setprop. Deleting (settings delete) isn't implemented yet.

adb_automation_mcp.modules.settings.tools

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

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

get_setting(ctx: Context, serial: str, namespace: SettingsNamespace, key: str, user_id: int | None = None) -> SettingValue async

Read one Android Settings-provider value: adb shell settings get NAMESPACE KEY.

namespace is restricted to "system", "secure", or "global" — the only namespaces settings get recognizes — by the tool's own input schema, so an invalid namespace is rejected before this tool (or any adb command) ever runs. Deliberately distinct from system_properties' get_property: Settings (SettingsProvider) and system properties (getprop/setprop) are unrelated Android subsystems. Writing a setting (put/delete) isn't implemented yet.

Parameters:

Name Type Description Default
serial str

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

 required
namespace SettingsNamespace

Which Settings namespace to read from: "system", "secure", or "global".

 required
key str

The setting's key, e.g. "screen_brightness".

 required
user_id int | None

Read the setting for one specific Android user (--user, see list_users). Omit to use settings' default user.

 None

Returns:

Type Description
SettingValue

The serial, namespace, key, user_id, and the setting's value. value is None when the key has no value in that namespace for the target user — see Error handling below for why that's returned as data, not raised.
Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. settings get reports a key with no value by printing the literal text "null" at exit code 0, not by failing — this tool returns that as value=None, ordinary success data, rather than an error (the one, rare ambiguity: a value that's coincidentally the literal string "null" is indistinguishable from "no value", the same class of caveat as get_property's empty-string case). A permission rejection raises PERMISSION_DENIED; any other failure raises a generic BACKEND_ERROR.

Example

Called with serial="emulator-5554", namespace="system", key="screen_brightness". A typical response:

{
  "status": "success",
  "message": "system:screen_brightness='128' on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "namespace": "system",
    "key": "screen_brightness",
    "value": "128",
    "user_id": null
  },
  "error": null
}
Source code in src/adb_automation_mcp/modules/settings/tools.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@category("read")
async def get_setting(
    ctx: Context, serial: str, namespace: SettingsNamespace, key: str, user_id: int | None = None
) -> SettingValue:
    """Read one Android Settings-provider value: `adb shell settings get NAMESPACE KEY`.

    namespace is restricted to "system", "secure", or "global" — the only
    namespaces `settings get` recognizes — by the tool's own input schema,
    so an invalid namespace is rejected before this tool (or any adb
    command) ever runs. Deliberately distinct from system_properties'
    get_property: Settings (SettingsProvider) and system properties
    (`getprop`/`setprop`) are unrelated Android subsystems. Writing a
    setting (`put`/`delete`) isn't implemented yet.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        namespace: Which Settings namespace to read from: "system",
            "secure", or "global".
        key: The setting's key, e.g. "screen_brightness".
        user_id: Read the setting for one specific Android user (`--user`,
            see list_users). Omit to use settings' default user.

    Returns:
        The serial, namespace, key, user_id, and the setting's value.
        value is None when the key has no value in that namespace for the
        target user — see Error handling below for why that's returned as
        data, not raised.

    Error handling:
        An unknown serial or unresponsive adb binary raises
        DEVICE_NOT_FOUND/ADB_UNAVAILABLE. `settings get` reports a key with
        no value by printing the literal text "null" at exit code 0, not
        by failing — this tool returns that as value=None, ordinary
        success data, rather than an error (the one, rare ambiguity: a
        value that's coincidentally the literal string "null" is
        indistinguishable from "no value", the same class of caveat as
        get_property's empty-string case). A permission rejection raises
        PERMISSION_DENIED; any other failure raises a generic
        BACKEND_ERROR.

    Example:
        Called with serial="emulator-5554", namespace="system",
        key="screen_brightness". A typical response:

        ```json
        {
          "status": "success",
          "message": "system:screen_brightness='128' on emulator-5554.",
          "data": {
            "serial": "emulator-5554",
            "namespace": "system",
            "key": "screen_brightness",
            "value": "128",
            "user_id": null
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    settings = cast(SettingsService, services["settings"])
    return await settings.get_setting(serial, namespace, key, user_id=user_id)

set_setting(ctx: Context, serial: str, namespace: SettingsNamespace, key: str, value: str, user_id: int | None = None) -> SettingWriteResult async

Write one Android Settings-provider value: adb shell settings put NAMESPACE KEY VALUE.

namespace is restricted to "system", "secure", or "global" by the tool's own input schema, so an invalid namespace is rejected before any adb command runs. The key is read once before the write and once after, so the result carries both previous_value (keep it to restore the original when your scenario is done) and new_value (what the provider reports now). Deliberately distinct from system_properties' set_property — Settings and system properties are unrelated Android subsystems. Deleting a setting (settings delete) isn't implemented yet.

Parameters:

Name Type Description Default
serial str

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

 required
namespace SettingsNamespace

Which Settings namespace to write to: "system", "secure", or "global".

 required
key str

The setting's key, e.g. "screen_brightness".

 required
value str

The value to write, as a string (numeric settings are still passed as their decimal text, e.g. "128"). Passed as a single shell-quoted argument.

 required
user_id int | None

Write the setting for one specific Android user (--user, see list_users). Omit to use settings' default user.

 None

Returns:

Type Description
SettingWriteResult

The serial, namespace, key, user_id, requested_value, previous_value (None if the key had no value before), new_value (None if it has none now), and changed (whether previous_value and new_value differ). new_value != requested_value is returned as-is, not raised — Android normalizes some values and silently ignores some protected keys, and that's a real device outcome worth seeing.
Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A namespace/key the device refuses to let the shell user write (SecurityException / "Permission Denial") raises PERMISSION_DENIED. settings put reaching SettingsProvider and being declined there (a Java stack trace / "Exception occurred while executing 'put'") raises ANDROID_REJECTED. Any other non-zero exit raises a generic BACKEND_ERROR.

Example

Called with serial="emulator-5554", namespace="system", key="screen_brightness", value="200". A typical response:

{
  "status": "success",
  "message": "Set system:screen_brightness = '200' on emulator-5554 (was '128').",
  "data": {
    "serial": "emulator-5554",
    "namespace": "system",
    "key": "screen_brightness",
    "requested_value": "200",
    "previous_value": "128",
    "new_value": "200",
    "user_id": null,
    "changed": true
  },
  "error": null
}
Source code in src/adb_automation_mcp/modules/settings/tools.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@category("write")
async def set_setting(
    ctx: Context,
    serial: str,
    namespace: SettingsNamespace,
    key: str,
    value: str,
    user_id: int | None = None,
) -> SettingWriteResult:
    """Write one Android Settings-provider value: `adb shell settings put NAMESPACE KEY VALUE`.

    namespace is restricted to "system", "secure", or "global" by the
    tool's own input schema, so an invalid namespace is rejected before any
    adb command runs. The key is read once before the write and once after,
    so the result carries both previous_value (keep it to restore the
    original when your scenario is done) and new_value (what the provider
    reports now). Deliberately distinct from system_properties' set_property
    — Settings and system properties are unrelated Android subsystems.
    Deleting a setting (`settings delete`) isn't implemented yet.

    Args:
        serial: The target device's adb serial (see list_connected_devices).
        namespace: Which Settings namespace to write to: "system", "secure",
            or "global".
        key: The setting's key, e.g. "screen_brightness".
        value: The value to write, as a string (numeric settings are still
            passed as their decimal text, e.g. "128"). Passed as a single
            shell-quoted argument.
        user_id: Write the setting for one specific Android user (`--user`,
            see list_users). Omit to use settings' default user.

    Returns:
        The serial, namespace, key, user_id, requested_value, previous_value
        (None if the key had no value before), new_value (None if it has
        none now), and changed (whether previous_value and new_value
        differ). new_value != requested_value is returned as-is, not raised
        — Android normalizes some values and silently ignores some
        protected keys, and that's a real device outcome worth seeing.

    Error handling:
        An unknown serial or unresponsive adb binary raises
        DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A namespace/key the device refuses
        to let the shell user write (SecurityException / "Permission
        Denial") raises PERMISSION_DENIED. `settings put` reaching
        SettingsProvider and being declined there (a Java stack trace /
        "Exception occurred while executing 'put'") raises ANDROID_REJECTED.
        Any other non-zero exit raises a generic BACKEND_ERROR.

    Example:
        Called with serial="emulator-5554", namespace="system",
        key="screen_brightness", value="200". A typical response:

        ```json
        {
          "status": "success",
          "message": "Set system:screen_brightness = '200' on emulator-5554 (was '128').",
          "data": {
            "serial": "emulator-5554",
            "namespace": "system",
            "key": "screen_brightness",
            "requested_value": "200",
            "previous_value": "128",
            "new_value": "200",
            "user_id": null,
            "changed": true
          },
          "error": null
        }
        ```
    """
    services = cast("dict[str, object]", ctx.lifespan_context["services"])
    settings = cast(SettingsService, services["settings"])
    return await settings.set_setting(serial, namespace, key, value, user_id=user_id)