안드로이드 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 기기에서 애플리케이션 실행
스크린샷을 찍어 로컬에 저장하거나 클립보드에 복사하세요
여러 기기 연결 시 스마트 기기 선택

🛠️ 사용 가능한 도구

도구	설명	필수 매개변수	선택적 매개변수
`adb_devices`	연결된 장치 나열	없음	없음
`adb_shell`	셸 명령 실행	`command`	`device_id`
`adb_install`	APK 파일 설치	`path`	`device_id`
`adb_uninstall`	애플리케이션 제거	`package_name`	`device_id`
`adb_list_packages`	설치된 패키지 목록	없음	`device_id` , `filter`
`adb_pull`	장치에서 파일 가져오기	`remote_path` , `local_path`	`device_id`
`adb_push`	장치에 파일 푸시	`local_path` , `remote_path`	`device_id`
`launch_app`	애플리케이션 실행	`package_name`	`device_id`
`take_screenshot_and_save`	스크린샷을 찍고 저장하세요	`output_path`	`device_id` , `format`
`take_screenshot_and_copy_to_clipboard`	클립보드에 스크린샷 찍기	없음	`device_id` , `format`

장치 관리

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

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

스크린샷 경로 해상도

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

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

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

🔍 문제 해결

일반적인 문제

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

🔧 대체 설치 방법

옵션 1: npm에서 설치

# Install globally
npm install -g @landicefu/android-adb-mcp-server

# Or install locally in your project
npm install @landicefu/android-adb-mcp-server

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

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

📄 라이센스

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

🤝 기여하기

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

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

Android ADB MCP Server

Integrations