📱 Phone MCP 플러그인
🌟 ADB 명령을 통해 Android 휴대폰을 손쉽게 제어할 수 있는 강력한 MCP 플러그인입니다.
예
- 브라우저별 오늘 날씨를 기반으로 넷이즈 음악을 자동으로 선택 및 재생합니다. 확인이 필요하지 않습니다.
- 연락처에서 하오에게 전화하세요. 받지 않으면 101호 회의실로 오라고 문자 메시지를 보내세요.
중국어 문서
⚡ 빠른 시작
📥 설치
지엑스피1
🔧 구성
AI 어시스턴트 구성
AI 어시스턴트 구성(Cursor, Trae, Claude 등)에서 다음을 구성하세요.
{
"mcpServers": {
"phone-mcp": {
"command": "uvx",
"args": [
"phone-mcp"
]
}
}
}
또는 pip로 설치한 경우:
{
"mcpServers": {
"phone-mcp": {
"command": "/usr/local/bin/python",
"args": [
"-m",
"phone_mcp"
]
}
}
}
중요 : 위 설정에서 /usr/local/bin/python 경로는 Python 인터프리터 경로입니다. 시스템의 실제 Python 설치 위치에 맞게 경로를 수정해야 합니다. 다양한 운영 체제에서 Python 경로를 찾는 방법은 다음과 같습니다.
Linux/macOS : 터미널에서 다음 명령을 실행하세요.
또는
Windows : 명령 프롬프트(CMD)에서 실행:
또는 PowerShell에서:
(Get-Command python).Path
구성에서 /usr/local/bin/python 전체 경로로 바꿔야 합니다. 예를 들어 Windows에서는 C:\Python39\python.exe 일 수 있습니다.
참고 : 커서의 경우 이 구성을 ~/.cursor/mcp.json 에 넣으세요.
용법:
- 예를 들어, Claude 대화에서 명령을 직접 사용하세요.
⚠️ 사용하기 전에 다음 사항을 확인하세요.
- ADB가 제대로 설치 및 구성되었습니다.
- Android 기기에서 USB 디버깅이 활성화되었습니다.
- 장치가 USB를 통해 컴퓨터에 연결되었습니다.
🎯 주요 특징
- 📞 통화 기능 : 전화 걸기, 전화 종료, 수신 전화 받기
- 💬 메시징 : SMS를 보내고 받고, 원시 메시지를 받습니다.
- 👥 연락처 : 휴대폰 연락처에 접근하고 자동화된 UI 상호 작용을 통해 새 연락처를 만듭니다.
- 📸 미디어 : 스크린샷, 화면 녹화, 미디어 제어
- 📱 앱 : 애플리케이션 실행, 인텐트를 사용하여 특정 활동 실행, 설치된 앱 나열, 앱 종료
- 🔧 시스템 : 창 정보, 앱 바로가기
- 🗺️ 지도 : 전화번호로 POI 검색
- 🖱️ UI 상호작용 : 탭, 스와이프, 텍스트 입력, 키 누르기
- 🔍 UI 검사 : 텍스트, ID, 클래스 또는 설명으로 요소 찾기
- 🤖 UI 자동화 : 요소를 기다리고, 스크롤하여 요소를 찾습니다.
- 🧠 화면 분석 : 구조화된 화면 정보 및 통합된 상호작용
- 🌐 웹 브라우저 : 기기의 기본 브라우저에서 URL을 엽니다.
- 🔄 UI 모니터링 : UI 변경 사항을 모니터링하고 특정 요소가 나타나거나 사라질 때까지 기다립니다.
🛠️ 요구 사항
- 파이썬 3.7 이상
- USB 디버깅이 활성화된 Android 기기
- ADB 도구
📋 기본 명령
장치 및 연결
# Check device connection
phone-cli check
# Get screen size
phone-cli screen-interact find method=clickable
의사소통
# Make a call
phone-cli call 1234567890
# End current call
phone-cli hangup
# Send SMS
phone-cli send-sms 1234567890 "Hello"
# Get received messages (with pagination)
phone-cli messages --limit 10
# Get sent messages (with pagination)
phone-cli sent-messages --limit 10
# Get contacts (with pagination)
phone-cli contacts --limit 20
# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"
미디어 및 앱
# Take screenshot
phone-cli screenshot
# Record screen
phone-cli record --duration 30
# Launch app (may not work on all devices)
phone-cli app camera
# Alternative app launch method using open_app (if app command doesn't work)
phone-cli open_app camera
# Close app
phone-cli close-app com.android.camera
# List installed apps (basic info, faster)
phone-cli list-apps
# List apps with pagination
phone-cli list-apps --page 1 --page-size 10
# List apps with detailed info (slower)
phone-cli list-apps --detailed
# Launch specific activity (reliable method for all devices)
phone-cli launch com.android.settings/.Settings
# Launch app by package name (may not work on all devices)
phone-cli app com.android.contacts
# Alternative launch by package name (if app command doesn't work)
phone-cli open_app com.android.contacts
# Launch app by package and activity (most reliable method)
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
# Open URL in default browser
phone-cli open-url google.com
화면 분석 및 상호작용
# Analyze current screen with structured information
phone-cli analyze-screen
# Unified interaction interface
phone-cli screen-interact <action> [parameters]
# Tap at coordinates
phone-cli screen-interact tap x=500 y=800
# Tap element by text
phone-cli screen-interact tap element_text="Login"
# Tap element by content description
phone-cli screen-interact tap element_content_desc="Calendar"
# Swipe gesture (scroll down)
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300
# Press key
phone-cli screen-interact key keycode=back
# Input text
phone-cli screen-interact text content="Hello World"
# Find elements
phone-cli screen-interact find method=text value="Login" partial=true
# Wait for element
phone-cli screen-interact wait method=text value="Success" timeout=10
# Scroll to find element
phone-cli screen-interact scroll method=text value="Settings" direction=down max_swipes=5
# Monitor UI for changes
phone-cli monitor-ui --interval 0.5 --duration 30
# Monitor UI until specific text appears
phone-cli monitor-ui --watch-for text_appears --text "Welcome"
# Monitor UI until specific element ID appears
phone-cli monitor-ui --watch-for id_appears --id "login_button"
# Monitor UI until specific element class appears
phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"
# Monitor UI changes with output as raw JSON
phone-cli monitor-ui --raw
위치 및 지도
# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000
📚 고급 사용법
앱 및 활동 시작
이 플러그인은 앱과 활동을 시작하는 여러 가지 방법을 제공합니다.
- 앱 이름으로 (두 가지 방법):
# Method 1: Using app command (may not work on all devices)
phone-cli app camera
# Method 2: Using open_app command (alternative if app command fails)
phone-cli open_app camera
- 패키지 이름으로 (두 가지 방법):
# Method 1: Using app command (may not work on all devices)
phone-cli app com.android.contacts
# Method 2: Using open_app command (alternative if app command fails)
phone-cli open_app com.android.contacts
- 패키지 및 활동별 (가장 신뢰할 수 있는 방법):
# This method works on all devices
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
참고 : app 이나 open_app 명령에서 문제가 발생하는 경우 항상 전체 구성 요소 이름(패키지/활동)과 함께 launch 명령을 사용하면 가장 안정적인 작업이 가능합니다.
UI 자동화를 통한 연락처 생성
이 플러그인은 UI 상호작용을 통해 연락처를 생성하는 방법을 제공합니다.
# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"
이 명령은 다음을 수행합니다.
- 연락처 앱을 엽니다
- 연락처 생성 인터페이스로 이동
- 이름과 전화번호 필드를 입력하세요
- 연락처를 자동으로 저장합니다
화면 기반 자동화
통합된 화면 상호작용 인터페이스를 통해 지능형 에이전트는 다음을 쉽게 수행할 수 있습니다.
- 화면 분석 : UI 요소 및 텍스트에 대한 구조화된 분석을 얻으세요
- 결정 내리기 : 감지된 UI 패턴과 사용 가능한 작업을 기반으로
- 상호작용 실행 : 일관된 매개변수 시스템을 통해
UI 모니터링 및 자동화
이 플러그인은 인터페이스 변경 사항을 감지하는 강력한 UI 모니터링 기능을 제공합니다.
- 기본 UI 모니터링 :
# Monitor any UI changes with custom interval (seconds)
phone-cli monitor-ui --interval 0.5 --duration 30
- 특정 요소가 나타날 때까지 기다리세요 :
# Wait for text to appear (useful for automated testing)
phone-cli monitor-ui --watch-for text_appears --text "Login successful"
# Wait for specific ID to appear
phone-cli monitor-ui --watch-for id_appears --id "confirmation_dialog"
- 모니터 요소가 사라짐 :
# Wait for text to disappear
phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
- 자세한 UI 변경 보고서 받기 :
# Get raw JSON data with all UI change information
phone-cli monitor-ui --raw
팁 : UI 모니터링은 자동화 스크립트가 로딩 화면이 완료될 때까지 기다리거나 UI에서 작업이 적용되었는지 확인하는 데 특히 유용합니다.
📚 자세한 문서
전체 문서와 구성 세부 정보를 보려면 GitHub 저장소를 방문하세요.
🧰 도구 문서
화면 인터페이스 API
이 플러그인은 기기와의 상호 작용을 위한 포괄적인 API를 갖춘 강력한 화면 인터페이스를 제공합니다. 주요 기능과 매개변수는 다음과 같습니다.
화면과 상호 작용
async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
"""Execute screen interaction actions"""
- 매개변수:
action : 동작 유형("탭", "스와이프", "키", "텍스트", "찾기", "대기", "스크롤")params : 각 작업 유형에 대한 매개변수가 포함된 사전
- 반환: 작업 결과가 포함된 JSON 문자열
예:
# Tap by coordinates
result = await interact_with_screen("tap", {"x": 100, "y": 200})
# Tap by element text
result = await interact_with_screen("tap", {"element_text": "Login"})
# Swipe down
result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})
# Input text
result = await interact_with_screen("text", {"content": "Hello world"})
# Press back key
result = await interact_with_screen("key", {"keycode": "back"})
# Find element by text
result = await interact_with_screen("find", {"method": "text", "value": "Settings", "partial": True})
# Wait for element to appear
result = await interact_with_screen("wait", {"method": "text", "value": "Success", "timeout": 10, "interval": 0.5})
# Scroll to find element
result = await interact_with_screen("scroll", {"method": "text", "value": "Privacy Policy", "direction": "down", "max_swipes": 8})
분석_화면
async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
"""Analyze the current screen and provide structured information about UI elements"""
- 매개변수:
include_screenshot : 결과에 base64로 인코딩된 스크린샷을 포함할지 여부max_elements : 처리할 UI 요소의 최대 개수
- 반환: 자세한 화면 분석이 포함된 JSON 문자열
연락처 생성
async def create_contact(name: str, phone: str) -> str:
"""Create a new contact with the given name and phone number"""
- 매개변수:
name : 연락처의 전체 이름phone : 연락처의 전화번호
- 반환: 작업 결과가 포함된 JSON 문자열
- 위치: 이 기능은 'contacts.py' 모듈에서 찾을 수 있으며 연락처를 생성하기 위한 UI 자동화를 구현합니다.
앱 실행 활동
async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
"""Launch an app using package name and optionally an activity name"""
- 매개변수:
package_name : 실행할 앱의 패키지 이름activity_name : 실행할 특정 활동(선택 사항)
- 반환: 작업 결과가 포함된 JSON 문자열
- 위치: 이 기능은 'apps.py' 모듈에서 찾을 수 있습니다.
발사 의도
async def launch_intent(intent_action: str, intent_type: Optional[str] = None, extras: Optional[Dict[str, str]] = None) -> str:
"""Launch an activity using Android intent system"""
- 매개변수:
intent_action : 수행할 작업intent_type : 인텐트의 MIME 유형(선택 사항)extras : 인텐트와 함께 전달할 추가 데이터(선택 사항)
- 반환: 작업 결과가 포함된 JSON 문자열
- 위치: 이 기능은 'apps.py' 모듈에서 찾을 수 있습니다.
📄 라이센스
아파치 라이선스, 버전 2.0
연락처 생성 도구
이 도구는 ADB를 사용하여 Android 기기에서 연락처를 만드는 간단한 방법을 제공합니다.
필수 조건
- 파이썬 3.x
- ADB(Android Debug Bridge) 설치 및 구성
- Android 기기가 연결되고 ADB에 승인됨
용법
기본 사용법
스크립트를 실행하기만 하면 됩니다.
이렇게 하면 기본값을 사용하여 연락처가 생성됩니다.
- 계정 이름: "你的账户name"
- 계정 유형: "com.google"
고급 사용법
JSON 문자열을 사용하여 사용자 지정 계정 이름과 유형을 제공할 수 있습니다.
python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'
산출
스크립트는 다음을 포함하는 JSON 객체를 출력합니다.
success : 작업이 성공했는지 여부를 나타내는 부울 값message : 명령의 출력이나 오류 메시지
성공 출력 예:
{"success": true, "message": ""}
오류 처리
- ADB를 사용할 수 없거나 장치가 연결되지 않은 경우 스크립트는 오류를 반환합니다.
- 잘못된 JSON 입력은 오류 메시지를 발생시킵니다.
- 모든 ADB 명령 오류는 캡처되어 메시지 필드에 반환됩니다.
노트
- Android 기기가 연결되어 있고 ADB 사용이 승인되었는지 확인하세요.
- 명령을 실행할 때 장치 화면 잠금이 해제되어야 합니다.
- 일부 기기에서는 연락처를 수정하기 위해 추가 권한이 필요할 수 있습니다.
앱 및 바로가기
# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"