Skip to main content
Glama
deenesjakoruzh
zalazp

adb-sms

by zalazp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

adb-sms MCP

Read Android SMS verification codes via ADB, enabling Cursor Agent to complete Web SMS login together with chrome-devtools.

Design principle: Phone numbers are configured by the user in devices.json; adb is only responsible for identifying the device serial + reading SMS OTP.

How It Works

USB 连接手机（adb devices → serial）
        │
        ├─ devices.json[serial].phone_numbers  →  Web 填手机号
        │
        └─ adb 读短信 inbox                    →  adb_wait_for_otp 拿验证码

Related MCP server: Android MCP Server

Project Structure

mcp-adb-sms/
├── server.py              # MCP 服务入口
├── adb_client.py          # ADB 设备 / 短信读取
├── sms_parser.py          # 短信与 OTP 解析
├── test_local.py          # 本地自检（不启动 MCP）
├── requirements.txt
├── devices.json.example   # 手机号配置模板（提交到 git）
├── devices.json           # 本地配置（git 忽略，需自行创建）
└── README.md

Prerequisites

  1. Android phone has USB debugging enabled and authorized on the computer

  2. adb devices shows device (not unauthorized)

  3. Python 3.10+ (3.12 recommended)

  4. Android platform-tools (includes adb)

Installation

git clone https://github.com/zalazp/mcp-adb-sms.git
cd mcp-adb-sms
py -3.12 -m pip install -r requirements.txt

Configure Phone Numbers (Required)

Phone numbers are not read by adb; write them into devices.json yourself:

copy devices.json.example devices.json

  1. Run adb devices and note the serial (e.g. 10AD410LNF000PX)

  2. Use the serial as the key and fill in all phone numbers for that device

{
  "10AD410LNF000PX": {
    "phone_numbers": [
      "18317840243",
      "19139582095"
    ]
  }
}

Cursor Configuration

Edit %USERPROFILE%\.cursor\mcp.json:

{
  "mcpServers": {
    "adb-sms": {
      "command": "py",
      "args": [
        "-3.12",
        "E:\\path\\to\\mcp-adb-sms\\server.py"
      ],
      "env": {
        "ADB_PATH": "D:\\RJAZ\\Sdk\\platform-tools\\adb.exe"
      }
    }
  }
}

Field

Description

Path in args

Change to the absolute path of server.py in the clone directory

ADB_PATH

Absolute path to local adb.exe; if already in PATH, write "adb"

After saving, restart Cursor; adb-sms in the MCP panel should turn green.

Local Self-Check

cd mcp-adb-sms
$env:ADB_PATH="D:\RJAZ\Sdk\platform-tools\adb.exe"
py -3.12 test_local.py

Example of normal output:

{
  "adb_exists": true,
  "devices": [{ "serial": "10AD410LNF000PX", "state": "device" }],
  "sms_readable": true,
  "sim_numbers": [
    { "number": "13800138000", "available": true },
    { "number": "13900139000", "available": true }
  ],
  "device_profile": { "source": "devices.json" }
}

If recommendations indicates missing configuration, create devices.json as described above.

MCP Tools

Tool

Description

adb_health_check

Diagnose adb, SMS readability, and whether devices.json is configured

adb_list_devices

List connected ADB devices

adb_get_sim_numbers

Read phone numbers for the current serial from devices.json

adb_read_recent_sms

Read the most recent N SMS messages

adb_wait_for_otp

After clicking send verification code on the Web, poll and wait for a new OTP

adb_grant_sms_permission

On Android 11+, attempt to grant shell permission to read SMS

adb_shell

Restricted adb shell (whitelisted commands)

Typical Agent Flow (SMS Login)

1. adb_health_check()
2. adb_get_sim_numbers()              ← 从 devices.json 取手机号
3. chrome-devtools: 打开登录页、填号、勾选协议
4. chrome-devtools: 滑块验证码（失败则人工完成）
5. chrome-devtools: 点击「发送验证码」
6. adb_wait_for_otp(timeout=90, sender_filter="Midea|美的")
7. chrome-devtools: 填入验证码并登录

When SMS Cannot Be Read

adb shell appops set com.android.shell READ_SMS allow

Or call adb_grant_sms_permission in the Agent, then run adb_health_check.

If it still fails, MCP will attempt to fall back to reading SMS from the notification bar via dumpsys notification (lower precision).

Security Notes

  • Only reads SMS from locally connected USB devices

  • Does not persist SMS content to disk

  • devices.json contains phone numbers and is in .gitignore; do not commit it to a public repository

  • adb_shell only allows whitelisted commands such as content / dumpsys / getprop

  • Restricted to your own devices or authorized test scenarios

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers