ADB MCP Server

ADB MCP 서버

ADB를 통해 안드로이드 기기와 상호작용하는 MCP(Model Context Protocol) 서버입니다. 이 TypeScript 기반 도구는 AI 모델과 안드로이드 기기 기능을 연결하는 다리 역할을 합니다.

특징

• 📱 기기 관리 - 연결된 Android 기기를 나열하고 상호 작용합니다.
• 📦 앱 설치 - 연결된 기기에 APK 파일 배포
• 📋 로깅 - Logcat을 통해 장치 로그에 액세스합니다.
• 🔄 파일 전송 - 장치와 호스트 간에 파일을 푸시하고 풀합니다.
• 📸 UI 상호작용 - 스크린샷을 캡처하고 UI 계층을 분석합니다.
• 🔧 셸 명령 실행 - 장치에서 사용자 지정 명령 실행

필수 조건

• Node.js(v16 이상 권장, Node.js v16, v18 및 v20으로 테스트됨)
• ADB(Android Debug Bridge)가 설치되고 PATH에 있음
• USB 디버깅이 활성화된 USB 또는 네트워크를 통해 연결된 Android 기기 또는 에뮬레이터
• 장치에 접근할 수 있는 권한(장치에서 디버깅 권한이 허용됨)

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 ADB Android Device Server를 자동으로 설치하려면:

지엑스피1

수동 설치

구성

ADB 경로 구성

서버는 기본 ADB 경로를 사용합니다. 사용자 지정 ADB 위치:

MCP 구성

ADB MCP 서버 구성을 추가합니다.

용법

서버 시작

중요: ADB 도구를 사용하려면 먼저 서버를 실행해야 합니다.

다음을 사용하여 서버를 시작합니다.

다음이 표시되어야 합니다.

ADB 도구를 사용하는 동안 이 터미널 창을 열어 두세요.

사용 가능한 도구

모든 도구는 다음과 같은 명명 규칙에 따라 사용할 수 있습니다.

📱 기기 관리

• adb_devices - 연결된 장치 나열
• adb_shell - 장치에서 셸 명령 실행

📦 앱 관리

• adb_install - 로컬 파일 경로를 사용하여 APK 파일 설치

📋 로깅

• adb_logcat - 선택적 필터링을 사용하여 장치 로그 보기

🔄 파일 전송

• adb_pull - 장치에서 파일 가져오기
• adb_push - 장치에 파일 푸시

🔍 UI 상호작용

• dump_image - 현재 화면의 스크린샷을 찍습니다.
• inspect_ui - XML 형식으로 UI 계층 구조 가져오기(AI 상호작용에 가장 유용함)

문제 해결

도구가 작동하지 않는 경우:

• 서버 문제:
  • 서버가 실행 중인지 확인하세요( npx adb-mcp )
  • 오류 메시지에 대한 서버 출력을 확인하세요.
  • 자세한 로그를 시도해 보세요: LOG_LEVEL=3 npx adb-mcp
  • 중단 프로세스 종료:
    • ps aux | grep "adb-mcp" | grep -v grep
    • 그런 다음 kill -9 [PID]
• 장치 연결:
  • adb_devices 로 연결 확인
  • "인증되지 않음"인 경우 장치에서 디버깅 권한을 수락합니다.
  • USB/네트워크 연결을 확인하세요
  • ADB를 다시 시작해 보세요: adb kill-server && adb start-server
• ADB 문제:
  • ADB 설치 확인: adb version
• 장치 설정:
  • 에뮬레이터를 사용하세요(에뮬레이터를 사용하여 만들었습니다). 실제 기기에서는 다음을 시도해 보세요.
    • USB 디버깅이 활성화되어 있는지 확인하세요
    • 최신 Android 버전의 경우 "USB 디버깅(보안 설정)"을 활성화하세요.
    • 다른 USB 포트나 케이블을 사용해 보세요
    • 또는 문제가 있을 경우 알려주세요

호환성

• 안드로이드 8.0 이상
• Cursor IDE의 Claude를 포함한 MCP 클라이언트
• macOS 기반으로 제작되었지만 POSIX 호환(Linux 등)에서도 실행 가능합니다 .
• 윈도우에서는 시도하지 않았지만 아마도 작동할 수도 있을 듯합니다.

기여하다

• 기여를 환영합니다! 풀 리퀘스트를 제출하세요.
• 중요한 변경 사항이 있는 경우 먼저 논의할 이슈를 개설하세요.
• 물론, 포크할 수도 있습니다.
• 참고: 이 프로젝트는 vibe-coded 되었으므로 이상한 점을 발견하더라도... 이제 알 수 있을 겁니다 🙂

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

• 모델 컨텍스트 프로토콜(MCP) 로 구축됨