Claude와 같은 LLM을 활용한 Android APK 분석용 JADX MCP Server

⚡ Claude와 같은 LLM (Large Language Models)을 사용하여 Android APK를 분석하기 위해 JADX-AI-MCP 플러그인과 통신하도록 구축된 완전 자동화된 MCP (Model Context Protocol) 서버입니다. 취약점을 발견하고, 매니페스트 (Manifest)를 파싱하며, 손쉽게 역공학 (Reverse Engineering)을 수행할 수 있습니다.

기여해 주신 멋진 분들께 감사드립니다 ⭐

현재 Read The Docs에서 확인 가능합니다:

JADX MCP Server는 MCP (Model Context Protocol)를 통해 수정된 버전의 jadx-gui (jadx-ai-mcp 참조)와 상호작용하는 독립형 Python 서버입니다. 이를 통해 LLM이 디컴파일된 Android 앱 컨텍스트 (Context)와 실시간으로 통신할 수 있게 해줍니다.

JADX-AI-MCP는 JADX 디컴파일러를 위한 플러그인으로, MCP (Model Context Protocol)와 직접 통합되어 Claude와 같은 LLM을 통한 실시간 역공학 (Reverse Engineering) 지원을 제공합니다.

— 특정 키워드를 포함하는 소스 코드를 가진 클래스 검색 (페이지네이션 지원)get_methods_of_class()

— 클래스의 메서드 목록 조회get_fields_of_class()

— 클래스의 필드 목록 조회get_smali_of_class()

— 클래스의 smali 코드 가져오기get_main_activity_class()

— AndroidManifest.xml 파일에 언급된 jadx로부터 메인 액티비티(Main Activity) 가져오기.get_main_application_classes_code()

— AndroidManifest.xml에 정의된 패키지 이름을 기반으로 모든 메인 애플리케이션 클래스의 코드 가져오기.get_main_application_classes_names()

— AndroidManifest.xml에 정의된 패키지 이름을 기반으로 모든 메인 애플리케이션 클래스의 이름 가져오기.get_android_manifest()

— AndroidManifest.xml 콘텐츠를 검색하여 반환get_manifest_component

전체 매니페스트 파일 대신 특정 매니페스트 컴포넌트(Component) 검색get_strings()

: strings.xml 파일을 가져옴get_all_resource_file_names()

: 애플리케이션에 존재하는 모든 리소스 파일 이름 조회get_resource_file()

: 리소스 파일 콘텐츠 조회rename_variable()

: 메서드 내의 변수 이름 변경debug_get_stack_frames()

: jadx 디버거(Debugger)에서 스택 프레임(Stack Frames) 가져오기debug_get_threads()

: jadx 디버거에서 스레드(Threads) 정보 조회debug_get_variables()

: jadx 디버거에서 변수(Variables) 조회xrefs_to_class()

: 클래스에 대한 모든 참조(References) 찾기 (메서드 수준 및 클래스 수준 참조 반환, 페이지네이션 지원)xrefs_to_method()

: 메서드에 대한 모든 참조 찾기 (오버라이드(Override) 관련 메서드 포함, 페이지네이션 지원)xrefs_to_field()

: 필드에 대한 모든 참조 찾기 (해당 필드에 접근하는 메서드 반환, 페이지네이션 지원)

🔍 기본적인 코드 이해 (Basic Code Understanding)

"이 클래스가 무엇을 하는지 한 단락으로 설명해줘."
"이 메서드의 역할을 요약해줘."
"이 클래스에 난독화 (Obfuscation)가 적용되어 있어?"
...

🛡️ 취약점 탐지 (Vulnerability Detection)

"이 메서드에 보안에 취약한 API 사용 사례가 있어?"
"이 클래스에 하드코딩된 비밀 값(Secrets)이나 자격 증명(Credentials)이 있는지 확인해줘."
"이 메서드는 사용자 입력값을 사용하기 전에 정제 (Sanitize) 과정을 거쳐?"
...

🛠️ 리버스 엔지니어링 도우미 (Reverse Engineering Helpers)

"클래스와 메서드를 읽기 쉬운 이름으로 난독화 해제 (Deobfuscate) 및 이름 변경해줘."
"이 smali 메서드의 원래 목적을 추론할 수 있어?"
"이 클래스는 어떤 라이브러리나 SDK의 일부인 것 같아?"

📦 정적 분석 (Static Analysis)

"이 클래스에 있는 모든 네트워크 관련 API 호출을 나열해줘."
"파일 I/O (Input/Output) 작업과 그에 따른 잠재적 위험을 식별해줘."
"이 메서드가 기기 정보나 개인정보 (PII)를 유출하니?"

🤖 AI 코드 수정 (AI Code Modification)

"가독성을 높이기 위해 이 메서드를 리팩터링 (Refactor)해줘."
"각 단계를 설명하는 주석을 이 코드에 추가해줘."
"분석을 위해 이 Java 메서드를 Python으로 다시 작성해줘."

📄 문서화 및 메타데이터 (Documentation & Metadata)

"모든 메서드에 대해 Javadoc 스타일의 주석을 생성해줘."
"이 클래스는 어떤 패키지나 앱 구성 요소 (App Component)에 속할 가능성이 높아?"
"Android 구성 요소 유형 (Activity, Service 등)을 식별할 수 있어?"

🐞 디버거 어시스턴트 (Debugger Assistant)

"디버거에서 스택 프레임 (Stack Frames), 변수 (Variables), 스레드 (Threads)를 가져와서 요약을 제공해줘."
"디버거의 스택 프레임을 바탕으로 애플리케이션의 실행 흐름을 설명해줘."
"변수의 상태를 바탕으로 보안 위협이 존재하니?"

데모: 로컬에서 취약점 탐지를 위한 코드 리뷰 수행하기

zin-mcp-client-2.mp4

두 개의 별도 연결이 존재하며, 각각 고유한 호스트/포트를 가집니다:

┌─────────────┐ --host / --port ┌──────────────────┐ --jadx-host / --jadx-port ┌──────────────────┐
│ LLM Client │ ◄──────────────────► │ jadx-mcp-server │ ──────────────────────────► │ JADX-GUI Plugin │
│ (Claude, │ MCP 서버가 위치한 곳 │ │ MCP 서버가 찾는 곳 │ (jadx-ai-mcp) │
...

| 플래그 (Flag) | 기본값 (Default) | 제어 항목 (Controls) |
|---|---|:|
| --http | off | stdio 대신 HTTP 전송 방식을 사용함 |
| --host | 127.0.0.1 | MCP 서버가 대기하는 위치 (LLM 클라이언트를 위한 바인드 주소) |
| --port | 8651 | MCP 서버가 대기하는 포트 |
| --jadx-host | 127.0.0.1 | JADX 플러그인을 찾을 위치 (대상 JADX-GUI 머신) |
| --jadx-port | 8650 | JADX 플러그인이 사용하는 포트 |

시나리오 1 — 모든 구성 요소가 동일한 머신에 있는 경우 (가장 일반적):

# 기본값: localhost:8651에서 MCP 서버 실행, localhost:8650의 JADX 플러그인에 연결
uv run jadx_mcp_server.py --http

시나리오 2 — Docker 컨테이너 또는 WSL 사용 시 (호스트 네트워크에서 MCP 서버에 접근 가능한 경우):

# 호스트가 접근할 수 있도록 MCP 서버가 모든 인터페이스(ALL interfaces)에서 대기
# JADX 플러그인은 여전히 동일한 머신에 있음
uv run jadx_mcp_server.py --http --host 0.0.0.0

시나리오 3 — JADX-GUI가 다른 머신(예: 원격 VM)에서 실행 중인 경우:

# MCP 서버는 로컬에서 실행되지만, 원격 머신의 JADX 플러그인에 연결
uv run jadx_mcp_server.py --http --jadx-host 192.168.1.100

시나리오 4 — 완전 원격 설정 (모든 구성 요소가 서로 다른 머신에 있는 경우):

# MCP 서버가 9999 포트의 모든 인터페이스에서 대기
# JADX 플러그인은 192.168.1.100:8652에 있는 다른 머신에 있음
uv run jadx_mcp_server.py --http --host 0.0.0.0 --port 9999 --jadx-host 192.168.1.100 --jadx-port 8652

주의 사항

--host 0.0.0.0을 사용할 때

(또는 localhost가 아닌 다른 주소를 사용할 때), MCP 서버는 **인증이 없는 일반 HTTP (plain HTTP)**를 통해 **모든 네트워크 인터페이스 (all network interfaces)**에 바인딩됩니다. 이는 다음을 의미합니다:

네트워크상의 누구라도 연결하여 모든 MCP 도구 (tools)를 호출할 수 있습니다.
TLS 암호화가 없으므로 트래픽이 가로채질 수 있습니다.
공격자가 서버를 사용하여 역컴파일된 코드를 읽고, 클래스/메서드 이름을 변경하며, 디버그 정보에 접근할 수 있습니다.

완화 방법:

신뢰할 수 있고 격리된 네트워크 (예: Docker bridge, 로컬 VM)에서만 0.0.0.0에 바인딩하십시오.
**방화벽 (firewall)**을 사용하여 MCP 포트에 대한 접근을 제한하십시오.
대신 SSH 터널 (SSH tunnel) 사용을 고려하십시오: ssh -L 8651:127.0.0.1:8651 remote-host

마찬가지로, localhost가 아닌 주소와 함께 --jadx-host를 사용하는 것은 MCP 서버가 해당 호스트에 **인증되지 않은 HTTP 요청 (unauthenticated HTTP requests)**을 보낸다는 것을 의미합니다. 대상이 신뢰할 수 있는지 확인하십시오.

apktool 지원 추가
hermes 코드 (ReactNative 애플리케이션) 지원 추가
Docker 지원 추가
더 유용한 MCP 도구 (Tools) 추가
LLM이 JADX에서 코드를 수정할 수 있도록 구현
프롬프트 템플릿 (Prompts templates) 추가, LLM이 Android APK 파일을 리소스 (Resources)로 액세스할 수 있도록 지원

~~로컬 LLM을 지원하는 MCP 클라이언트 (MCP Client) 구축~~-
최종 목표 (END-GOAL): 모든 Android 역공학 (Reverse engineering) 및 APK 수정 도구들을 단일 MCP 서버에 연결하여, 순수하게 느낌 (Vibes)만으로 APK 파일을 역공학하는 과정을 최대한 쉽게 만드는 것.

JADX-AI-MCP와 관련된 파일들은 여기서 찾을 수 있습니다.

jadx-mcp-server와 관련된 파일들은 오직 이 저장소(Repository)에만 있습니다.

이 프로젝트는 @skylot이 제작하고 유지 관리하는 놀라운 오픈 소스 Android 디컴파일러 (Decompiler)인 JADX를 위한 플러그인입니다. 모든 핵심 디컴파일 로직은 그들에게 속해 있습니다. 저는 오직 AI 기능을 갖춘 저의 MCP 서버를 지원하기 위해 이를 확장했을 뿐입니다.

참조 및 출처 표기를 위해 JADX의 원본 README.md가 이 저장소에 포함되어 있습니다.

이 MCP 서버는 JADX-GUI의 확장성과 놀라운 Android 역공학 커뮤니티 덕분에 가능했습니다.

또한 Debian 기반 Linux용 Claude Desktop을 개발해 준 @aaddrick에게도 큰 감사를 전합니다.

그리고 마지막으로 Model Context Protocol (MCP)을 개발한 @Anthropic과 @FastMCP 팀에게 감사를 전합니다.

또한 이와 같은 프로젝트를 가능하게 하는 라이브러리와 의존성 (Dependencies)을 만드는 모든 오픈 소스 유지 관리자 및 기여자들에게 감사드립니다.

감사 및 평가 배지 (Assessment Badge)를 제공해 준 Mseep.net에 감사드립니다.

이 프로젝트는 다음과 같은 멋진 라이브러리들을 사용합니다.

플러그인 (Plugin) - Java

Javalin - https://javalin.io/ - Apache 2.0 License
SLF4J - https://slf4j.org/ - MIT License
org.w3c.dom - https://mvnrepository.com/artifact/org.w3c.dom - W3C Software and Document License

MCP 서버 (MCP Server) - Python

FastMCP - https://github.com/jlowin/fastmcp - Apache 2.0 License
httpx - https://www.python-httpx.org - BSD-3-Clause (“BSD licensed”)

이 플러그인은 원본 JADX 저장소로부터 Apache 2.0 License를 상속받습니다.

면책 조항 (Disclaimer)

jadx-ai-mcp 및 jadx_mcp_server 도구는

교육, 연구 및 윤리적인 보안 평가 (security assessment) 목적으로만 사용되어야 합니다. 이 도구들은 명시적이든 묵시적이든 어떠한 보증 없이 "있는 그대로" 제공됩니다. 사용자는 이러한 도구의 사용이 모든 관련 법률, 규정 및 윤리적 가이드라인을 준수하는지 확인해야 할 전적인 책임이 있습니다.

jadx-ai-mcp 또는 jadx_mcp_server를 사용함으로써, 귀하는 귀하가 소유하거나 분석에 대한 명시적인 권한을 가진 애플리케이션과 같이 테스트 권한이 있는 환경에서만 이 도구들을 사용하기로 동의합니다. 승인되지 않은 역공학 (reverse engineering), 지적 재산권 침해 또는 악의적인 활동을 위해 이 도구들을 오용하는 것은 엄격히 금지됩니다.

jadx-ai-mcp 및 jadx_mcp_server의 개발자들은 이 도구들의 사용 또는 오용으로 인해 발생하는 어떠한 손해, 데이터 손실, 법적 결과 또는 기타 결과에 대해서도 책임을 지지 않습니다. 사용자는 자신의 행동과 사용으로 인해 발생하는 모든 영향에 대해 모든 책임을 집니다.

책임감 있게 사용하십시오. 지적 재산권을 존중하십시오. 윤리적 해킹 (ethical hacking) 관행을 준수하십시오.

유용하셨나요? ⭐️를 눌러주세요
아이디어가 있나요? Issue를 오픈하거나 PR을 제출해 주세요
이를 기반으로 무언가를 만드셨나요? 저에게 DM을 보내거나 언급해 주세요 — README에 추가해 드리겠습니다!

역공학 (reverse engineering) 및 AI 커뮤니티를 위해 ❤️를 담아 만들었습니다.

Claude와 같은 LLM을 활용한 Android APK 분석용 JADX MCP Server

요약

핵심 포인트

zin-mcp-client-2.mp4

댓글