Termux API 및 PRoot-Distro Ubuntu와 MCP 서버

이 프로젝트는 Termux를 통해 Android의 proot-distro 아래에 Ubuntu를 설치하고, Android 시스템 API를 바인딩하며, Python 기반 Model Context Protocol (MCP) 서버를 실행하는 부트스트랩 스크립트를 제공합니다.

이 MCP 서버를 휴대폰에서 실행하면, 외부 AI 클라이언트(Cursor, Claude Desktop, Windsurf 또는 사용자 정의 HTTP 에이전트 등)에게 Android 기기의 하드웨어 제어, 센서 읽기, 통신 데이터 가져오기, 셸 명령 실행 등 전체 기능을 부여할 수 있습니다.

빠른 시작 (3단계 설정)

1단계: Termux에 Ubuntu 설치 및 구성

네이티브 Termux 터미널에서 이 명령을 실행하여 Ubuntu를 설치, 구성하고 로그인합니다. (이 명령은 스크립트를 먼저 다운로드하므로 stdin이 키보드에 연결된 상태로 유지되어 올바르게 로그인할 수 있습니다.)

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

이 스크립트가 완료되면 자동으로 Ubuntu에 로그인되어 다음 프롬프트가 표시됩니다: root@localhost:~#

2단계: MCP 클론 및 설정 (Ubuntu 내부)

Ubuntu 컨테이너(root@localhost:~#)에 들어간 후, 이 명령을 복사하여 붙여넣어 저장소를 클론하고 설정 스크립트를 실행한 다음 가상 환경을 활성화합니다:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

(source venv/bin/activate 문을 추가하면 상위 셸 컨텍스트에서 실행됩니다. 완료되면 프롬프트 (venv)root@localhost:~/Termux-MCP#가 표시된 활성화된 가상 환경 안에 있게 됩니다.)

3단계: MCP 서버 실행

활성화된 가상 환경 내에서 서버를 직접 실행합니다:

python termux_mcp.py --transport sse

서버가 실행되면 휴대폰의 IP 주소를 감지하여 AI 클라이언트에 직접 연결할 수 있는 복사-붙여넣기 가능한 연결 URL(예: http://192.168.1.15:8000/sse)을 표시합니다!

향후 단축 명령

향후 실행 시(네이티브 Termux에서 수동 로그인 및 활성화 없이) 한 번의 명령으로 서버를 시작할 수 있습니다:

proot-distro login ubuntu -- bash /root/run_mcp.sh

Related MCP server: android-shizuku-mcp

왜 PRoot-Distro Ubuntu인가?

proot-distro를 사용하여 Termux 내부에서 Ubuntu와 같은 Linux 배포판을 실행하면 몇 가지 주요 이점이 있습니다:

1. Glibc (GNU C Library) 호환성: Android와 네이티브 Termux는 경로와 표준이 다른 Bionic libc를 사용합니다. 많은 컴파일된 패키지, 데이터베이스 바이너리, Node 모듈 및 Python 라이브러리는 컴파일 오류 없이 실행하려면 표준 glibc가 필요합니다. PRoot-Distro Ubuntu는 표준 glibc 환경을 제공합니다.

2. 패키지 풍부함 및 생태계: Ubuntu는 방대한 apt 패키지 아카이브에 대한 액세스를 제공합니다. 워크플로에 표준 Linux 서버 도구, 데스크톱 패키지 또는 컴파일된 서비스가 필요한 경우, Ubuntu rootfs에서 실행하는 것이 네이티브 Android/Bionic용으로 패치하는 것보다 훨씬 더 안정적입니다.

3. 격리 및 샌드박스: PRoot Ubuntu 내부에서 개발하면 호스트 Termux 파일시스템을 깨끗하고 모듈식으로 유지할 수 있습니다. 문제가 발생하거나 새로 시작하려면 Termux 구성을 잃지 않고 배포판 컨테이너를 간단히 재설정할 수 있습니다.

4. 하드웨어 API 브리징: 부트스트랩 스크립트는 Termux 네이티브 $PREFIX 폴더를 Ubuntu에 바인딩합니다. 즉, Android API(카메라, 토스트, 위치, 센서 등)에 대한 직접적인 명령줄 액세스를 유지하면서도 완전한 기능을 갖춘 Ubuntu Linux 환경이라는 두 가지 장점을 모두 얻을 수 있습니다.

기능 (MCP 도구)

MCP 서버는 휴대폰을 제어하기 위한 완전한 도구 세트를 제공합니다:

• 시스템 및 하드웨어:

  • get_battery_status: 기기 배터리 잔량, 상태, 온도 및 충전 상태를 읽습니다.

  • toggle_torch: 손전등/토치를 켜거나 끕니다.

  • set_screen_brightness: 화면 밝기를 변경합니다 (0-255).

  • get_volume_info 및 set_volume: 알람, 음악, 벨소리, 통화, 시스템 및 알림 볼륨 스트림의 레벨을 읽거나 설정합니다.

• 통신:

  • list_contacts: 휴대폰에 저장된 모든 연락처 이름과 전화번호를 나열합니다.

  • get_call_log: 최근 통화 기록을 가져옵니다.

  • list_sms 및 send_sms: 받은 편지함/보낸 메시지를 나열하고 새 문자 메시지를 보냅니다.

• 센서 및 네트워크:

  • get_location: 정밀한 GPS 또는 네트워크 기반 좌표를 가져옵니다.

  • get_wifi_connection_info: Wi-Fi 연결 메타데이터(SSID, BSSID, IP, 링크 속도)를 가져옵니다.

  • get_telephony_device_info: 통신사, 신호 강도 및 네트워크 유형을 조회합니다.

• 미디어 및 사진:

  • take_photo: 전면 또는 후면 카메라 사진을 촬영하여 기기의 파일 경로에 저장합니다.

  • tts_speak: Google TTS를 사용하여 음성 합성을 생성합니다.

• 사용자 상호작용 및 클립보드:

  • show_toast: 휴대폰 화면에 임시 토스트 알림을 표시합니다.

  • vibrate_phone: 설정된 시간 동안 기기를 진동시킵니다.

  • clipboard_get 및 clipboard_set: Android 클립보드를 읽고 씁니다.

  • show_notification: 표준 Android 알림을 표시합니다.

  • prompt_user_dialog: 휴대폰에 대화형 텍스트 입력 대화상자를 표시하여 AI 클라이언트에 응답을 입력할 수 있게 합니다.

  • share_text: 텍스트를 Android의 네이티브 공유 시트에 직접 공유합니다.

• 임의 실행:

  • execute_command: 네이티브 Termux 호스트에서 임의의 셸 명령을 직접 실행합니다.

상세 단계별 설치

1단계: Android에 Termux 및 Termux:API 설치

1. Termux 앱과 Termux:API 앱을 설치합니다.

   • 필수: 두 앱을 모두 F-Droid에서 설치합니다 (F-Droid와 Play Store 버전을 혼합하지 마세요. 함께 서명/바인딩되지 않습니다).

2. Android 설정 -> 앱 -> Termux:API -> 권한으로 이동합니다:

   • 카메라, 위치, SMS, 연락처 및 저장 공간 권한을 부여합니다.

3. Android가 백그라운드 서비스를 종료하지 않도록 Termux 및 Termux:API 모두에 대해 배터리 최적화를 비활성화합니다.

2단계: 설정 스크립트 실행

Termux를 열고 다음 명령을 붙여넣습니다:

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

3단계: MCP 서버 설정 실행

Ubuntu 컨테이너에 들어간 후:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

4단계: 서버 실행

활성화된 환경((venv)root@localhost:~/Termux-MCP#)에서:

python termux_mcp.py --transport sse

터미널에 연결 URL이 출력됩니다:

==================================================================
   🤖 Termux MCP Server Running in SSE Mode
==================================================================
   👉 SSE Connect URL: http://192.168.1.15:8000/sse
   👉 Messages URL:    http://192.168.1.15:8000/messages/
==================================================================

5단계: AI 클라이언트에 연결

Server-Sent Events (SSE)를 통한 MCP를 지원하는 모든 클라이언트를 연결할 수 있습니다.

Cursor 연결:

1. Cursor 설정 -> Features -> MCP를 엽니다.

2. + Add New MCP Server를 클릭합니다.

3. 입력:

   • 이름: termux-mcp

   • 유형: SSE

   • URL: http://YOUR_PHONE_IP:8000/sse (서버가 출력한 'SSE Connect URL'을 복사하여 붙여넣습니다)

4. Save를 클릭합니다.

Claude Desktop 연결 (SSH를 통한 대체 Stdio)

SSH를 통해 파이프된 로컬 stdio 명령을 실행하려면 저장소 문서의 Option B를 참조하여 OpenSSH 키를 설정하고 로컬 %APPDATA%\Claude\claude_desktop_config.json을 구성하세요.

문제 해결

• 도구 호출이 멈춤: 도구 호출(get_location 또는 take_photo 등)이 멈추면 Termux:API 앱에 Android 설정에서 권한이 부여되었는지, 배터리 절약 모드가 꺼져 있는지 확인하세요.

• 연결 거부: PC와 휴대폰이 동일한 Wi-Fi 네트워크에 연결되어 있고 서버가 실행 중인지 확인하세요.

• Termux 백그라운드 실행: Android는 화면이 잠겨 있을 때 Termux 프로세스를 일시 중단할 수 있습니다. Android 알림 서랍을 내려서 Termux에 "Acquire wake lock"이 활성화된 "1 session"이 표시되어 백그라운드에서 계속 실행되는지 확인하세요.