Android ADB MCP Server

안드로이드 ADB MCP 서버

AI 어시스턴트가 안드로이드 디버그 브리지(ADB)를 통해 안드로이드 기기와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 AI 기능과 안드로이드 기기 관리 간의 간극을 메워 안드로이드 개발 및 테스트 작업의 원활한 자동화를 지원합니다.

⚙️ 빠른 설정

MCP 구성 파일에 서버를 추가합니다.

지엑스피1

구성 위치

• Claude Desktop : ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cline/Roo 코드 : ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json (macOS)
• Windows/Linux의 경우 해당 애플리케이션 지원 디렉토리를 확인하세요.

구성 후 AI 어시스턴트를 다시 시작하여 새로운 서버 구성을 로드합니다.

📋 필수 조건

• ADB(Android Debug Bridge)가 시스템 PATH에 설치되어 사용 가능해야 합니다.
  • Windows, macOS 또는 Linux에 ADB 설치
  • 터미널에서 adb version 실행하여 설치를 확인하세요.
• 클립보드 기능을 사용하려면:
  • macOS : osascript (내장)
  • Windows : PowerShell(내장)
  • Linux : xclip ( apt-get install xclip 또는 이와 동등한 명령어를 통해 설치)
• Node.js 16.x 이상

🚀 특징

• 여러 Android 기기에 연결하고 관리하세요
• Android 기기에서 셸 명령 실행
• 애플리케이션 설치 및 제거
• 로컬 시스템과 Android 기기 간에 파일을 푸시하고 풀합니다.
• Android 기기에서 애플리케이션 실행
• 스크린샷을 찍어 로컬에 저장하거나 클립보드에 복사하세요
• 여러 기기 연결 시 스마트 기기 선택

🛠️ 사용 가능한 도구

장치 관리

서버는 장치 선택을 지능적으로 처리합니다.

• 1개의 기기만 연결된 경우 자동으로 사용됩니다.
• 여러 장치가 연결된 경우 device_id 매개변수를 지정해야 합니다.
• 장치가 연결되지 않으면 오류가 반환됩니다.

스크린샷 경로 해상도

스크린샷을 저장하기 위해 output_path 지정할 때 경로는 다음과 같이 확인됩니다.

• 절대 경로는 그대로 사용됩니다.
• ~ 로 시작하는 경로는 사용자의 홈 디렉토리로 확장됩니다.
• 상대 경로는 사용자의 홈 디렉토리를 기준으로 확인됩니다.

이렇게 하면 스크린샷이 MCP 서버에 쓰기 권한이 있는 위치에 저장됩니다.

🔍 문제 해결

일반적인 문제

1. "ADB를 사용할 수 없습니다" 오류
   • ADB가 설치되어 있고 시스템 PATH에 있는지 확인하세요.
   • 터미널에서 adb version 실행하여 확인하세요.
2. "연결된 Android 기기가 없습니다" 오류
   • adb devices 로 기기가 제대로 연결되었는지 확인하세요
   • 장치에서 USB 디버깅이 활성화되어 있는지 확인하세요.
   • adb kill-server 실행한 후 adb start-server 실행하여 ADB를 다시 시작해 보세요.
3. "여러 기기가 연결됨" 오류
   • 도구 호출에서 device_id 매개변수를 지정하세요.
   • adb_devices 도구를 사용하여 사용 가능한 장치 목록을 가져옵니다.
4. 클립보드에 스크린샷을 찍는 기능이 작동하지 않습니다.
   • 필수 플랫폼별 도구가 설치되어 있는지 확인하세요.

🔧 대체 설치 방법

옵션 1: npm에서 설치

옵션 2: 소스에서 수동 설치

1. 저장소를 복제합니다.
   git clone https://github.com/landicefu/android-adb-mcp-server.git cd android-adb-mcp-server
2. 종속성을 설치하고 빌드합니다.
   npm install npm run build
3. 직접 경로로 구성:
   { "mcpServers": { "android-adb": { "command": "node", "args": ["/path/to/android-adb-mcp-server/build/index.js"], "env": {}, "disabled": false, "alwaysAllow": [] } } }

📄 라이센스

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

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
4. 브랜치에 푸시( git push origin feature/amazing-feature )
5. 풀 리퀘스트 열기