Skip to main content
Glama
adb-sms
by zalazp

adb-sms MCP

ADB를 통해 Android SMS 인증 코드를 읽어 Cursor Agent가 chrome-devtools와 함께 웹 SMS 로그인을 완료할 수 있게 합니다.

설계 원칙: 휴대폰 번호는 사용자가 devices.json에 구성합니다. adb는 기기 serial 식별 + SMS OTP 읽기만 담당합니다.

작동 원리

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

Related MCP server: ScoutlyMCP

프로젝트 구조

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

사전 요구 사항

  1. Android 휴대폰에서 USB 디버깅을 켜고 PC를 승인합니다

  2. adb devices에 device로 표시됩니다(unauthorized 아님)

  3. Python 3.10+(3.12 권장)

  4. Android platform-tools(adb 포함)

설치

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

휴대폰 번호 구성(필수)

휴대폰 번호는 adb가 읽지 않습니다. 직접 devices.json에 작성하세요:

copy devices.json.example devices.json
  1. adb devices를 실행하고 serial을 기록합니다(예: 10AD410LNF000PX)

  2. serial을 key로 하여 해당 휴대폰의 모든 휴대폰 번호를 입력합니다

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

Cursor 구성

%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"
      }
    }
  }
}

필드

설명

args의 경로

clone 디렉터리의 server.py 절대 경로로 변경

ADB_PATH

로컬 adb.exe 절대 경로; PATH에 있으면 "adb"로 작성

저장 후 Cursor를 재시작하면 MCP 패널에서 adb-sms가 녹색으로 표시됩니다.

로컬 자체 점검

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

정상 출력 예시:

{
  "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" }
}

recommendations에 구성 누락이 표시되면 위 내용에 따라 devices.json을 생성합니다.

MCP 도구

도구

설명

adb_health_check

adb, SMS 읽기 가능 여부, devices.json 구성 여부 진단

adb_list_devices

연결된 ADB 기기 나열

adb_get_sim_numbers

devices.json에서 현재 serial의 휴대폰 번호 읽기

adb_read_recent_sms

최근 N개 SMS 읽기

adb_wait_for_otp

웹에서 인증 코드 전송 클릭 후 새 OTP 폴링 대기

adb_grant_sms_permission

Android 11+에서 shell이 SMS를 읽도록 권한 부여 시도

adb_shell

제한된 adb shell(화이트리스트 명령)

Agent 일반적인 흐름(SMS 로그인)

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: 填入验证码并登录

SMS를 읽을 수 없을 때

adb shell appops set com.android.shell READ_SMS allow

또는 Agent에서 adb_grant_sms_permission을 호출한 후 adb_health_check를 실행합니다.

그래도 실패하면 MCP는 dumpsys notification으로 알림 표시줄 SMS를 대체 읽기 시도합니다(정확도 낮음).

보안 설명

  • USB로 연결된 로컬 기기의 SMS만 읽습니다

  • SMS 내용을 디스크에 영구 저장하지 않습니다

  • devices.json에 휴대폰 번호가 포함되어 있으며 .gitignore에 있습니다. 공개 저장소에 커밋하지 마세요

  • adb_shell은 content / dumpsys / getprop 등 화이트리스트 명령만 허용합니다

  • 본인 기기 또는 승인된 테스트 시나리오로만 제한됩니다

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables an agent to inspect and interact with Android emulators or physical devices via ADB, capturing UI snapshots, tapping nodes, typing text, and reading app logs.
      10
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to use a real Android phone with a SIM to retrieve phone numbers, receive SMS verification codes, and manage SMS messages.
      -