bethington/ghidra-mcp

이 프로젝트가 유용하다고 생각하신다면 ⭐ star를 눌러주세요 — 다른 사람들이 이 프로젝트를 발견하는 데 큰 도움이 됩니다!

Ghidra MCP가 시간을 절약해 주었다면, 프로젝트 후원을 고려해 주세요. 일회성 및 정기적 후원은 호환성 업데이트, 프로덕션 강화 (production hardening), 문서화 및 새로운 툴링을 위한 자금 마련에 도움이 됩니다.

Ghidra의 강력한 역공학 (reverse engineering) 기능과 현대적인 AI 도구 및 자동화 프레임워크를 연결하는 프로덕션 준비 완료된 Model Context Protocol (MCP) 서버입니다. 245개의 MCP 도구, 실전에서 검증된 AI 워크플로우 (workflows), 그리고 현재 사용 가능한 가장 포괄적인 Ghidra-MCP 통합 기능을 제공합니다 — 이제 P-code 에뮬레이션 (emulation), 라이브 디버거 (live debugger) 통합, 그리고 PCode-graph 데이터 흐름 분석 (data flow analysis) 기능이 포함됩니다.

대부분의 Ghidra MCP 구현체는 몇 가지 읽기 전용 (read-only) 도구만을 제공하고 끝납니다. 이 프로젝트는 다릅니다 — 데모용이 아니라, 실제 바이너리 (binaries)에서 매일 이를 사용하는 역공학 전문가에 의해 구축되었습니다.

245개의 MCP 도구 — 경쟁 구현체보다 3배 더 많습니다. 단순한 읽기 작업뿐만 아니라 이름 변경 (renaming), 타입 지정 (typing), 주석 달기 (commenting), 구조체 생성 (structure creation), 스크립트 실행 (script execution), P-code 에뮬레이션 및 라이브 디버깅을 위한 완전한 쓰기 권한 (write access)을 제공합니다. 실전에서 검증된 AI 워크플로우 — 수백 개의 함수를 거치며 정제된 검증된 문서화 워크플로우 (V5)를 포함합니다. 단계별 프롬프트 (prompts), 헝가리안 표기법 (Hungarian notation) 참조, 배치 처리 (batch processing) 가이드 및 고립된 코드 (orphaned code) 발견 기능이 포함됩니다. 프로덕션급 신뢰성 — 원자적 트랜잭션 (Atomic transactions), 배치 작업 (API 호출 93% 감소), 설정 가능한 타임아웃 (timeouts), 그리고 우아한 에러 핸들링 (graceful error handling)을 제공합니다. 조용한 실패 (silent failures)는 없습니다. 바이너리 간 문서 전송 — SHA-256 함수 해시 매칭을 통해 바이너리 버전 간에 문서가 자동으로 전파됩니다. 한 번만 문서화하면 어디든 적용됩니다. 전체 Ghidra 서버 통합 — 공유 Ghidra 서버에 연결하고, 리포지토리 (repositories)를 관리하며, 버전 관리, 체크아웃/체크인 (checkout/checkin) 워크플로우 및 다중 사용자 협업을 수행할 수 있습니다. Headless 및 GUI 모드 — Ghidra GUI 유무에 관계없이 실행할 수 있습니다.

CI/CD 파이프라인 및 대규모 자동화 분석을 위한 Docker 지원. 설계 단계부터 반영된 확고한 원칙 (Opinionated by design) — v5.0은 명명 규칙 (naming conventions), 타입 안정성 (type safety), 그리고 문서화 표준을 도구 계층 (tool layer)으로 이동시킵니다. 이를 통해 AI 에이전트와 인간 엔지니어는 모든 프롬프트에 스타일 가이드를 포함하지 않고도 일관된 결과물을 생성할 수 있습니다.

이런 경험이 있으실 겁니다: 프로젝트를 시작한 지 6개월 만에 동일한 코드베이스 내에서 ProcessItem, process_items, handleItem, ItemProc를 발견하는 상황 말입니다. 네 개의 함수가 동일한 작업을 수행하고 있지만, 공유된 계약 (shared contract) 없이 네 명의 서로 다른 세션이나 엔지니어에 의해 명명된 것입니다. 이를 수정하는 데는 예상보다 더 많은 시간이 걸리며

Full MCP Compatibility— Model Context Protocol (MCP)의 완전한 구현
245 MCP Tools— 바이너리 분석 (binary analysis)의 모든 측면을 다루는 포괄적인 API 표면
Production-Ready Reliability— 원자적 트랜잭션 (Atomic transactions), 배치 작업 (batch operations), 설정 가능한 타임아웃 (timeouts)
Real-time Analysis— Ghidra 분석 엔진과의 실시간 통합

호환성 참고 사항: MCP 도구 이름은 GitHub Copilot CLI 및 CAPI 검증을 위해 정규화되었습니다. 노출된 도구 이름은 소문자, 숫자, 언더스코어(_), 하이픈(-)만 사용합니다. /debugger/status와 같은 중첩된 HTTP 경로는 정적 브리지 도구와의 충돌을 피해야 할 경우 debugger_status_2와 같은 이름으로 표시됩니다.

Function Analysis— 디컴파일 (Decompilation), 호출 그래프 (call graphs), 교차 참조 (cross-references), 완전성 점수 (completeness scoring)
Data Flow Analysis— 임의의 변수 또는 레지스터로부터의 PCode-graph 값 전파 (forward / backward)
Data Structure Discovery— 필드 분석 및 명명 제안을 포함한 Struct/union/enum 생성
String Extraction— 정규 표현식 (Regex) 검색, 품질 필터링, 그리고 문자열 기반 함수 발견 (string-anchored function discovery)
Import/Export Analysis— 심볼 테이블 (Symbol tables), 외부 위치 (external locations), 오디널 임포트 해소 (ordinal import resolution)
Memory & Data Inspection— 로우 메모리 읽기 (Raw memory reads), 바이트 패턴 검색, 배열 경계 탐지
Cross-Binary Documentation— 함수 해시 매칭 및 버전 간 문서 전파

P-code Emulation— Ghidra의 EmulatorHelper를 통해 임의의 함수를 격리하여 실행; 밀리초 단위의 브루트 포스 (brute-force) API 해시 해소
Live Debugger Integration— Ghidra의 TraceRmi 프레임워크를 통한 17개의 Java 엔드포인트 + 22개의 Python 브리지 도구 (Windows PE의 경우 dbgeng, 그 외에는 gdb/lldb): 어태치 (attach), 스텝 (step), 브레이크포인트 (breakpoints), 레지스터 (registers), 메모리 읽기, 중단 없는 함수 트레이싱 (non-breaking function tracing), ASLR을 인식하는 정적↔동적 주소 변환

함수 문서화 워크플로우 V5 (Function Documentation Workflow V5)— Hungarian notation, 타입 감사 (type auditing), 자동 검증 점수 산출을 포함한 완전한 함수 문서화를 위한 7단계 프로세스
배치 문서화 (Batch Documentation)— 여러 함수를 동시에 문서화하기 위한 병렬 서브에이전트 (subagent) 파견
고립된 코드 발견 (Orphaned Code Discovery)— 알려진 코드 사이의 간극에서 발견되지 않은 함수를 찾는 자동 스캐너
데이터 타입 조사 (Data Type Investigation)— 구조체 발견 및 필드 분석을 위한 체계적인 워크플로우
교차 버전 매칭 (Cross-Version Matching)— 서로 다른 바이너리 버전 간의 해시 기반 함수 매칭

Ghidra 스크립트 관리 (Ghidra Script Management)— MCP를 통해 Ghidra 스크립트를 생성, 실행, 업데이트 및 삭제
멀티 프로그램 지원 (Multi-Program Support)— 여러 개의 열려 있는 프로그램 간 전환 및 비교
배치 작업 (Batch Operations)— 대량의 이름 변경, 주석 달기, 타입 지정 및 레이블 관리 (API 호출 93% 감소)
헤드리스 서버 (Headless Server)— Ghidra GUI 없이 전체 분석 수행 — Docker 및 CI/CD 환경 지원
프로젝트 및 버전 관리 (Project & Version Control)— 프로젝트 생성, 파일 관리, Ghidra Server 통합
분석 제어 (Analysis Control)— Ghidra 분석기 (analyzers)를 프로그래밍 방식으로 나열, 구성 및 트리거

Java 21 LTS (OpenJDK 권장)
Apache Maven 3.9+
Ghidra 12.1 (또는 호환 가능한 버전)
Python 3.10+ (pip 포함)

Ghidra Server 공유 사용자: Ghidra 12.1 클라이언트는 12.1, 12.0.5 또는 그 이상의 호환 가능한 버전의 Ghidra Server가 필요합니다. 12.1 클라이언트에서 이 플러그인을 사용하기 전에 서버를 업그레이드하십시오.

Ghidra 12.1은 선택적 확장 기능으로 Jython을 제공합니다. Java 스크립트는 기본적으로 작동하지만, ghidra_scripts/ 디렉토리 내의 .py 스크립트를 사용하려면 File > Install Extensions에서 Jython 확장을 설치하고 Ghidra를 재시작해야 합니다.

모든 플랫폼에 권장되는 방법: python -m tools.setup을 직접 사용하십시오.

ensure-prereqs는 런타임 Python 요구 사항과 로컬 Maven 저장소에 필요한 Ghidra JAR 파일을 설치합니다. deploy는 빌드 결과물을 복사하고, 사용자 프로필 확장을 설치하며, Ghidra 사용자 설정을 패치합니다.

저장소 클론 (Clone the repository):
git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp

권장 사항: 환경 사전 점검(preflight)을 먼저 실행하세요:
python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1_PUBLIC"

Ghidra에 빌드 및 배포:
python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1_PUBLIC"

deploy 명령은 필요한 경우 이미 실행 중인 일치하는 Ghidra 인스턴스를 저장하거나 종료하고, 확장 기능(extension)을 설치하며, Ghidra를 시작하고, MCP 상태를 기다린 후, 스키마 스모크 테스트(schema smoke checks)를 실행합니다.

선택적 엄격/수동 모드 (고급):
# 자동 필수 구성 요소 설정 건너뛰기 python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1_PUBLIC"

명령어 도움말 표시:
python -m tools.setup --help

선택적 빌드 전용 모드 (고급/문제 해결):
python -m tools.setup build

지원되는 빌드 경로:

python -m tools.setup build는 내부적으로 Maven을 사용하며, 리포지토리(repo) 작업 및 문서에서 사용하는 표준 워크플로(workflow)입니다.

# 수동 Maven 빌드 (로컬 .m2에 Ghidra 의존성이 이미 설치되어 있어야 함) mvn clean package assembly:single -DskipTests

# 보조/수동 Gradle 빌드 경로 (tools.setup 또는 VS Code 작업에서 사용되지 않음) GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

리포지토리 클론(Clone):
git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp

시스템 필수 구성 요소 설치 (이미 설치되지 않은 경우):
sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip curl jq unzip

환경 사전 점검(preflight) 실행:
python -m tools.setup preflight --ghidra-path ~/ghidra_12.1_PUBLIC

Ghidra에 빌드 및 배포 (단일 명령):
python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1_PUBLIC

이 명령은 다음을 수행합니다:

• Ghidra JAR 의존성을 로컬 ~/.m2/repository에 설치합니다.
• GhidraMCP-<version>.zip을 빌드합니다.

Maven을 사용하여 - 확장 프로그램을 다음 경로에 압축 해제합니다:
~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/

• LastExtensionImportDirectory를 포함하여 preferences 업데이트

• Python 요구 사항 설치

• Ghidra JAR 의존성을 로컬에 설치합니다.

• 선택 사항: Maven 의존성만 설정: python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1_PUBLIC

• 명령어 도움말 표시: python -m tools.setup --help

Linux 경로: 확장 프로그램은 $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/에 설치됩니다. Ghidra 설정 파일은 $HOME/.config/ghidra/ghidra_<version>_PUBLIC/에 있습니다.

• 필수 구성 요소 설치: brew install openjdk@21 maven python ghidra

• 저장소 복제 (Clone): git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp

• Ghidra JAR를 로컬 Maven에 설치: python -m tools.setup install-ghidra-deps --ghidra-path /opt/homebrew/opt/ghidra/libexec

• 빌드 및 배포: python -m tools.setup ensure-prereqs --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy --ghidra-path /opt/homebrew/opt/ghidra/libexec

확장 프로그램은 ~/Library/ghidra/ghidra_12.1_PUBLIC/Extensions/GhidraMCP/에 설치됩니다.

참고: Homebrew 경로를 사용할 때는 경로에 버전 문자열이 포함되어 있지 않으므로 --ghidra-version이 필요합니다.

• Ghidra를 실행하고 플러그인 활성화: /opt/homebrew/opt/ghidra/libexec/ghidraRun

메인 프로젝트 창에서:

Tools > GhidraMCP > Start MCP Server

• Cursor/Claude MCP 설정 (~/.cursor/mcp.json):
  { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--script", "/path/to/ghidra-mcp/bridge_mcp_ghidra.py"] } } }

@Pandoriaantje가 커뮤니티 AUR 패키지를 관리합니다:

ghidra-mcp-git — main 브랜치를 추적합니다.

ghidra-mcp — 태그된 릴리스 (tagged releases)를 추적합니다.

원하는 AUR 헬퍼를 사용하여 설치하세요. 예시:

yay -S ghidra-mcp # 또는 ghidra-mcp-git

python bridge_mcp_ghidra.py

python bridge_mcp_ghidra.py --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

HTTP 전송 (transport) 방식을 위한 MCP 클라이언트 설정 (클라이언트의 MCP 설정 파일에 추가하세요):

{
"mcpServers": {
"ghidra-mcp-http": {
...

python bridge_mcp_ghidra.py --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

플래그 (Flag)	기본값 (Default)	설명 (Description)
--transport	stdio	stdio (AI 도구용), streamable-http (웹 클라이언트용), sse (사용 중단 예정)
--mcp-host	127.0.0.1	HTTP 전송 방식을 위한 바인드 호스트 (Bind host)
--mcp-port	—	HTTP 전송 방식을 위한 포트 (Port)
--lazy	off	연결 시 기본 도구 그룹만 로드합니다. 시작 속도는 더 빠르지만, tools/list_changed를 지원하지 않는 MCP 클라이언트는 불완전한 도구 목록을 보게 됩니다. Claude Code에는 권장되지 않습니다.
--no-lazy	(기본값)	연결 시 즉시 모든 도구 그룹을 로드합니다. 대부분의 AI 클라이언트에 필요합니다.
--default-groups	listing,function,program	--lazy가 설정되었을 때 연결 시 로드되는 쉼표로 구분된 그룹들

python -m pip install -r requirements-debugger.txt
python -m debugger

디버거 (debugger) 서버는 기본적으로 http://127.0.0.1:8099/에서 대기하며, MCP 브리지(bridge)에 의해 노출되는 debugger_* 프록시 도구들을 사용하기 위해 반드시 필요합니다.

디버거 서버 플래그 (Debugger server flags):