Ghidra MCP 서버

이 도구가 유용하다면, ⭐ 스타(star)를 눌러주세요. 다른 사람들이 발견하는 데 도움이 됩니다!

Ghidra MCP가 시간을 절약해 준다면, 프로젝트 후원을 고려해 주세요. 일회성 및 정기 후원 모두 호환성 업데이트, 프로덕션 안정성 강화, 문서, 새로운 도구 제작에 도움이 됩니다.

Ghidra의 강력한 리버스 엔지니어링 기능과 현대 AI 도구 및 자동화 프레임워크를 연결하는 프로덕션 환경에 적합한 Model Context Protocol (MCP) 서버입니다. 271개의 MCP 도구, 실전 검증된 AI 워크플로우, 그리고 가장 포괄적인 Ghidra-MCP 통합을 제공합니다. 이제 P-code 에뮬레이션, 라이브 디버거 통합, PCode 그래프 데이터 흐름 분석이 포함됩니다.

Ghidra MCP를 선택해야 하는 이유

대부분의 Ghidra MCP 구현체는 소수의 읽기 전용 도구만 제공하고 그걸로 끝입니다. 이 프로젝트는 다릅니다. 데모용이 아니라 실제 바이너리를 매일 분석하는 리버스 엔지니어에 의해 만들어졌습니다.

• 271개의 MCP 도구 — 경쟁 구현체보다 3배 많습니다. 단순한 읽기 작업이 아닙니다. 이름 변경, 타입 지정, 주석 작성, 구조체 생성, 스크립트 실행, P-코드 에뮬레이션 및 라이브 디버깅을 위한 전체 쓰기 액세스를 제공합니다.
• 실전 검증된 AI 워크플로우 — 수백 개의 함수에 걸쳐 개선된 검증된 문서화 워크플로우(V5)입니다. 단계별 프롬프트, 헝가리안 표기법 참조, 배치 처리 가이드 및 고립된 코드 검색이 포함됩니다.
• 프로덕션 수준의 안정성 — 원자적 트랜잭션, 일괄 작업(API 호출 93% 감소), 구성 가능한 타임아웃 및 우아한 오류 처리를 제공합니다. 무음 오류가 없습니다.
• 바이너리 간 문서 전송 — SHA-256 함수 해시 매칭이 바이너리 버전 간에 문서를 자동으로 전파합니다. 한 번 문서화하고 모든 곳에 적용하세요.
• 전체 Ghidra 서버 통합 — 공유 Ghidra 서버 연결, 저장소 관리, 버전 관리, 체크아웃/체크인 워크플로우 및 다중 사용자 협업을 지원합니다.
• 헤드리스 및 GUI 모드 — Ghidra GUI 유무에 관계없이 실행 가능합니다. Docker를 지원하여 CI/CD 파이프라인 및 대규모 자동화 분석에 사용할 수 있습니다.
• 설계상 명확한 철학 — v5.0은 명명 규칙, 타입 안전성 및 문서화 표준을 도구 계층으로 이동합니다. AI 에이전트와 인간 엔지니어가 모든 프롬프트에 스타일 가이드를 붙여넣지 않고도 일관된 결과물을 생성할 수 있습니다.

규칙 적용

경험해 보셨을 겁니다: 프로젝트를 시작한 지 6개월이 지나면 같은 코드베이스에서 ProcessItem, process_items, handleItem, ItemProc를 발견하게 됩니다. 네 개의 함수가 동일한 작업을 수행하지만, 네 번의 다른 세션이나 엔지니어가 공유된 규칙 없이 이름을 지은 것입니다. 수정하는 데 예상보다 오래 걸리며, 문제는 다시 발생할 것입니다.

v5.0은 규칙을 "기억해야 할 사항"에서 실제로 적용될 수 있는 도구 계층으로 이동합니다.

AI 에이전트의 경우, 이는 모든 세션, 모든 모델, 모든 실행에서 스타일 가이드를 매 프롬프트에 붙여넣지 않아도 일관된 출력을 의미합니다. 도구가 규칙을 알고 있으며, 모델은 결정만 내리면 됩니다.

팀의 경우, "그건 우리 명명 규칙이 아니야"라는 유형의 코드 리뷰 코멘트가 완전히 사라집니다. 규칙 중재는 코드 리뷰가 아닌 도구에서 이루어집니다.

대규모 단독 작업의 경우, analyze_function_completeness는 정직하게 측정하는 0–100% 점수를 제공합니다. 구조적 공제(수정 불가능한 컴파일러 아티팩트)는 유효 점수에서 용서되며, 로그 스케일링은 하나의 나쁜 카테고리가 모든 것을 묻지 못하게 하고, 계층화된 플레이트 주석 품질은 무엇이 누락되었고 그 이유를 정확히 알려줍니다.

🌟 주요 기능

핵심 MCP 통합

• 전체 MCP 호환성 — Model Context Protocol의 완전한 구현
• 271개의 MCP 도구 — 바이너리 분석의 모든 측면을 포괄하는 포괄적인 API 표면
• 프로덕션 준비 완료된 안정성 — 원자적 트랜잭션, 일괄 작업, 구성 가능한 타임아웃
• 실시간 분석 — Ghidra 분석 엔진과의 라이브 통합

호환성 참고: MCP 도구 이름은 GitHub Copilot CLI 및 CAPI 검증을 위해 정규화됩니다. 노출되는 도구 이름은 소문자, 숫자, 밑줄, 하이픈만 사용합니다. /debugger/status와 같은 중첩 HTTP 경로는 정적 브리지 도구와의 충돌을 피하기 위해 필요 시 debugger_status_2와 같은 이름으로 광고됩니다.

바이너리 분석 기능

• 함수 분석 — 디컴파일, 호출 그래프, 상호 참조, 완전성 점수
• 데이터 흐름 분석 — 모든 변수 또는 레지스터에서 PCode 그래프 값 전파(순방향/역방향)
• 데이터 구조 검색 — 필드 분석 및 명명 제안을 포함한 구조체/공용체/열거형 생성
• 문자열 추출 — 정규식 검색, 품질 필터링 및 문자열 기반 함수 검색
• 가져오기/내보내기 분석 — 심볼 테이블, 외부 위치, 서수 가져오기 해결
• 메모리 및 데이터 검사 — 원시 메모리 읽기, 바이트 패턴 검색, 배열 경계 감지
• 바이너리 간 문서화 — 함수 해시 매칭 및 버전 간 문서 전파

동적 분석 (v5.4.0)

• P-코드 에뮬레이션 — Ghidra의 EmulatorHelper를 통해 격리된 상태로 모든 함수 실행; 수 밀리초 내에 API 해시 무차별 대입 해결
• 라이브 디버거 통합 — Ghidra의 TraceRmi 프레임워크를 통한 17개의 Java 엔드포인트 + 22개의 Python 브리지 도구(Windows PE에서는 dbgeng, 그 외에는 gdb/lldb): 연결, 단계 실행, 중단점, 레지스터, 메모리 읽기, 중단 없는 함수 추적, ASLR 인식 정적↔동적 주소 변환

AI 기반 리버스 엔지니어링 워크플로우

• 함수 문서화 워크플로우 V5 — 헝가리안 표기법, 타입 감사, 자동화된 검증 점수를 포함한 완전한 함수 문서화를 위한 7단계 프로세스
• 배치 문서화 — 여러 함수를 동시에 문서화하기 위한 병렬 하위 에이전트 디스패치
• 고립된 코드 검색 — 알려진 코드 사이의 간격에서 발견되지 않은 함수를 찾는 자동화된 스캐너
• 데이터 타입 조사 — 구조체 검색 및 필드 분석을 위한 체계적인 워크플로우
• 버전 간 매칭 — 다양한 바이너리 버전 간 해시 기반 함수 매칭

개발 및 자동화

• Ghidra 스크립트 관리 — MCP를 통해 Ghidra 스크립트 생성, 실행, 업데이트 및 삭제
• 다중 프로그램 지원 — 여러 열린 프로그램 간 전환 및 비교
• 일괄 작업 — 대량 이름 변경, 주석 달기, 타입 지정 및 레이블 관리(API 호출 93% 감소)
• 헤드리스 서버 — Ghidra GUI 없이 전체 분석 지원 — Docker 및 CI/CD 준비 완료
• 프로젝트 및 버전 관리 — 프로젝트 생성, 파일 관리, Ghidra 서버 통합
• 분석 제어 — 프로그래밍 방식으로 Ghidra 분석기 나열, 구성 및 트리거

🚀 빠른 시작

필수 구성 요소

• Java 21 LTS (OpenJDK 권장)
• Apache Maven 3.9+
• Ghidra 12.1.2 (또는 호환 버전)
• Python 3.10+ 및 uv (권장) 또는 pip + venv

공유 Ghidra 서버 사용자: Ghidra 12.1.2 클라이언트는 Ghidra 서버 12.1, 12.0.5 또는 최신 호환 버전이 필요합니다. 12.1 클라이언트에서 이 플러그인을 사용하기 전에 서버를 업그레이드하세요.

Ghidra 12.1.2는 Jython을 선택적 확장 기능으로 제공합니다. Java 스크립트는 기본적으로 작동하지만, ghidra_scripts/ 디렉토리의 .py 스크립트는 파일 > 확장 기능 설치에서 Jython 확장 기능을 설치하고 Ghidra를 다시 시작해야 합니다.

설치

모든 플랫폼에서 권장: python -m tools.setup을 직접 사용하세요.

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

1. 저장소를 클론합니다: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. 권장: 먼저 환경 사전 점검을 실행하십시오: ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. Ghidra에 빌드 및 배포: ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy는 이미 실행 중인 일치하는 Ghidra 인스턴스를 필요 시 저장/닫고, 확장 프로그램을 설치하며, Ghidra를 시작하고, MCP 상태를 기다린 후 스키마 스모크 테스트를 실행합니다.

4. 선택적 엄격/수동 모드 (고급): ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. 명령 도움말 표시: ```text python -m tools.setup --help
   root@kitploit:~

6. 빌드 전용 모드 선택 사항 (고급/문제 해결): ```text python -m tools.setup build
   root@kitploit:~

지원되는 빌드 경로: python -m tools.setup build는 내부적으로 Maven을 사용하며, 리포지토리 작업과 문서에서 사용되는 표준 워크플로입니다. ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

입력:   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

설치 (Linux — Ubuntu/Debian)

1. 저장소를 클론하세요: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. 시스템 사전 요구 사항 설치 (아직 설치되지 않은 경우): ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

Debian/Kali/Ubuntu 23.04+ 참고 (PEP 668): 이 배포판들은 시스템 Python을 외부 관리로 표시하므로 일반적인 pip install은 error: externally-managed-environment 오류와 함께 실패합니다. --break-system-packages로 해결하지 마세요. apt로 관리되는 도구를 손상시킬 수 있습니다. 대신 uv를 사용하세요 (권장 — 자동으로 프로젝트 로컬 .venv를 생성 및 관리하며, 이 저장소의 명령어가 사용하는 방식입니다):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # resolves deps into .venv and starts the bridge

또는 클래식 가상 환경:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

3. 환경 사전 점검 실행: ```bash python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

4. Ghidra에 빌드 및 배포 (단일 명령어): ```bash python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

이렇게 하면 다음과 같은 작업이 수행됩니다:

• Ghidra JAR 종속성을 로컬 ~/.m2/repository에 설치합니다.
• Maven을 사용하여 GhidraMCP-<version>.zip을 빌드합니다.
• 확장 프로그램을 ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/에 추출합니다.
• LastExtensionImportDirectory로 preferences를 업데이트합니다.
• Python 요구 사항을 설치합니다.

5. 선택 사항: Maven 종속성만 설정: ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. 명령어 도움말 표시: ```bash python -m tools.setup --help
   root@kitploit:~

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

설치 (macOS — Homebrew)

1. 전제 조건 설치: ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. 저장소를 클론하세요: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. 로컬 Maven에 Ghidra JARs 설치: ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. 빌드 및 배포: ```bash 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
   root@kitploit:~

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

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

5. Ghidra를 시작하고 플러그인을 활성화하세요: ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

기본 프로젝트 창에서: Tools > GhidraMCP > Start MCP Server

6. Cursor/Claude MCP 구성 (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

설치 (Arch Linux — AUR)

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

• ghidra-mcp-git — main 브랜치를 추적
• ghidra-mcp — 릴리즈 태그를 추적

원하는 AUR 헬퍼를 사용하여 설치하세요. 예:```bash yay -S ghidra-mcp # or ghidra-mcp-git

### 기본 사용법

#### 옵션 1: Stdio 전송 (AI 도구에 권장)```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

클론 체크아웃에서 Autohand Code에 브리지를 추가하려면:```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Add `--scope project` before `ghidra` to save the server in the current project's `.autohand` configuration instead of your user configuration.

#### Option 2: Streamable HTTP Transport (Recommended for web/HTTP clients)```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

HTTP 전송을 위한 MCP 클라이언트 구성 (클라이언트의 MCP 구성 파일에 추가):```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

브라우저 기반 클라이언트(예: [MCP Inspector](https://github.com/modelcontextprotocol/inspector))는 즉시 사용 가능합니다. HTTP 전송은 CORS 사전 요청(`OPTIONS`)에 응답하고 `mcp-session-id` / `mcp-protocol-version` 헤더를 스크립트에 노출합니다. 허용된 출처는 Host-헤더 정책을 따릅니다. 모든 포트의 루프백은 항상 허용되며, 바인드 호스트와 `GHIDRA_MCP_ALLOWED_HOSTS`에 나열된 모든 호스트도 허용됩니다.

#### 옵션 3: SSE 전송 (사용 중단됨 — 대신 streamable-http 사용)```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

브리지 고급 플래그

엄격한 프로그램 라우팅 (다중 프로그램 안전성)

GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1를 설정하면 브리지가 프로그램 선택자를 생략하는 모든 프로그램 범위 호출을 거부하고, 호출이 서버의 공유 "현재 프로그램"(switch_program과 활성 GUI 탭이 이동하는 대상)을 사용하지 못하도록 대신 명확한 오류를 반환합니다.```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

이것이 없으면, `program=`을 생략한 호출은 현재 활성화된 프로그램을 대상으로 실행됩니다. 단일 프로그램 워크플로우에서는 문제가 없지만 여러 프로그램이 열려 있을 때는 위험합니다. 해당 호출이 오류 없이 잘못된 바이너리를 읽거나 편집할 수 있기 때문입니다. 여러 클라이언트가 서버를 공유할 때는 위험이 더 커집니다. 각 클라이언트가 현재 프로그램 전역 변수를 서로의 동의 없이 변경하기 때문입니다.

엄격 모드가 켜져 있으면 모든 프로그램 범위의 호출은 대상을 지정해야 합니다. 이는 열려 있는 프로그램을 선택하는 모든 선택자를 포함합니다: 단순 `program=`, 교차 프로그램 도구의 `source_program`/`target_program` 또는 `program_a`/`program_b` (필수로 선언되었지만, 값이 비어 있으면 서버는 여전히 현재 프로그램으로 대체됩니다). 선택자를 잊어버리면 잘못된 바이너리에 조용히 쓰는 대신 첫 번째 잘못된 호출에서 큰 오류가 발생합니다. 프로그램 선택자가 없는 도구(`open_program` 및 `close_program`은 `path`/`name`을 사용함)는 영향을 받지 않습니다. 기본적으로 꺼져 있습니다: 변수가 설정되지 않으면 브리지는 호출을 변경하지 않고 보냅니다.

#### 도구 컨텍스트 오버헤드 줄이기

브리지는 큰 카탈로그를 제공합니다. 모델의 도구 표면을 작게 유지하려면 `--lazy` 옵션으로 실행하고 (연결 시 `listing,function,program`만 로드) 모델이 모든 것을 등록하는 대신 필요에 따라 나머지를 **발견**하도록 합니다:

- `search_tools("rename function")` — 그룹이 로드되지 않은 도구를 포함하여 **전체** 카탈로그를 키워드 검색합니다. 각 결과는 현재 호출 가능한지 여부와, 그렇지 않은 경우 활성화하기 위한 정확한 `load_tool_group(...)` 호출을 알려줍니다.
- `list_tool_groups()` — 모든 카테고리와 로드 상태를 나열합니다.
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — 런타임에 카테고리를 로드하거나 제거합니다.
- `check_tools("rename_or_label,batch_set_comments")` — 특정 도구가 현재 호출 가능한지 확인합니다.

`search_tools`는 즉시 모드와 `--lazy` 모드 모두에서 작동하므로, `tools/list_changed`를 따르는 에이전트는 초기 컨텍스트 비용 없이 전체 검색을 수행할 수 있습니다.

#### 선택 사항: 독립형 디버거 서버 시작```bash
uv sync --group debugger
uv run python -m debugger

The debugger server listens on http://127.0.0.1:8099/ by default and is required for the debugger_* proxy tools exposed by the MCP bridge.

Debugger server flags:

기본 포트나 호스트를 변경한 경우 브리지가 찾을 수 있도록 .env 파일에서 GHIDRA_DEBUGGER_URL을 설정하세요.

Ghidra에서

1. Ghidra를 시작하고 CodeBrowser 창을 엽니다.
2. CodeBrowser에서 File > Configure > Configure All Plugins > GhidraMCP를 통해 플러그인을 활성화합니다.
3. 선택 사항: CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server에서 사용자 지정 포트를 구성합니다.
4. Tools > GhidraMCP > Start MCP Server를 통해 서버를 시작합니다.
5. 서버는 기본적으로 http://127.0.0.1:8089/에서 실행됩니다.

작동 확인```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## 이 프로젝트 지원하기

Ghidra MCP가 엔지니어링 또는 리버스 엔지니어링 시간을 절약해 준다면, [프로젝트 후원](https://github.com/sponsors/bethington)을 고려해 주세요.

- 일회성 후원은 버그 수정, 호환성 업데이트, 릴리스 작업 자금 지원에 도움이 됩니다.
- 정기 후원은 유지보수, 문서, 프로덕션 강화 작업이 계속 진행되도록 합니다.
- 기업 후원은 브리지, 헤드리스 서버, 디버거 통합 및 워크플로 도구의 장기적인 안정성에 우선순위를 두는 데 도움이 됩니다.

## 🔒 보안

GhidraMCP는 **로컬호스트 전용 개발**을 위해 설계되었습니다. 기본 설정(`127.0.0.1`에 바인딩된 HTTP 서버, 인증 없음)은 신뢰할 수 있는 단일 사용자 워크스테이션에서 안전하며 v5.4.1 이전 동작과 일치합니다.

**루프백을 넘어 서버를 노출하려면 먼저 이 세 가지 환경 변수를 구성하세요.** 서버는 토큰 없이 루프백이 아닌 바인드에서 시작을 거부합니다.

| 환경 변수 | 효과 |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | 설정된 경우 모든 HTTP 요청은 `Authorization: Bearer <token>`을 포함해야 합니다. 타이밍 안전 비교. `/mcp/health`, `/health`, `/check_connection`은 면제됩니다. |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | `/run_script_inline` 및 `/run_ghidra_script`를 활성화하려면 `1`, `true` 또는 `yes`로 설정하세요. **v5.4.1부터 기본적으로 꺼져 있음** — 이 엔드포인트는 Ghidra 프로세스에 대해 임의의 Java를 실행합니다. 헤드리스 모드에서는 서버 시작 시 OSGi `BundleHost` 초기화도 트리거합니다(Felix 프레임워크, ~수백 ms). 스크립트 실행이 필요하지 않으면 꺼두세요. |
| `GHIDRA_MCP_FILE_ROOT` | 디렉터리 경로로 설정된 경우, 파일 시스템 경로 엔드포인트(`/load_program`, `/import_file`, `/open_project`, `/delete_file` 등)는 입력을 정규화하고 이 루트 아래에 있어야 합니다. 경로 탐색을 방지합니다. |

이름 품질 강화는 보안과 별개입니다. 기본적으로 `rename_function_by_address` 및 전역 쓰기 엔드포인트는 내장 품질 게이트를 통과하지 못하는 이름을 거부하며, 구조체 필드 쓰기는 내장 필드 접두사 규칙을 적용합니다. **Edit > Tool Options > GhidraMCP HTTP Server > Strict Naming Enforcement**에서 내장 규칙 레이어를 비활성화할 수 있습니다. 동일한 Tool Options 체크박스는 `rename_data`, `rename_global_variable`, `set_global`, `apply_data_type` 접두사/타입 가드, 그리고 `create_struct`, `add_struct_field`, `modify_struct_field`의 구조체 필드 헝가리안 접두사 자동 수정을 다룹니다. 이 설정은 MCP 서버가 시작되거나 다시 시작될 때 읽힙니다. 강화가 비활성화되어도 함수/전역 규칙 경고는 여전히 반환됩니다.

### 예: 인증으로 사설 LAN에 노출```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

Ghidra 서버 인증

공유 Ghidra 서버에 연결할 때 GhidraMCP가 자동으로 비밀번호 대화상자를 표시하지 않도록 할 수 있습니다. 다음 순서대로 자격 증명을 확인합니다(처음으로 비어 있지 않은 값이 사용됨):

호환성 참고: Ghidra 12.1.2 클라이언트는 Ghidra Server 12.1.2, 12.0.5 또는 더 새로운 호환 서버가 필요합니다. 이전 공유 서버는 12.1 클라이언트 업그레이드의 안전한 대상이 아닙니다.

1. GHIDRA_SERVER_PASSWORD 환경 변수 (또는 Ghidra 설치 디렉터리나 ~의 .env 파일)
2. ~/.ghidra-cred — 홈 디렉터리의 한 줄 비밀번호 파일
3. <ghidra-install-dir>/.ghidra-cred

사용자 이름도 유사하게 확인됩니다: GHIDRA_SERVER_USER 환경 변수 → user.name 시스템 속성.

비밀번호가 없으면 Ghidra가 일반 GUI 프롬프트를 표시합니다. 무음 인증을 활성화하려면 .env에서 설정하십시오(전체 블록은 .env.template 참조).

v5.4.0에서 v5.4.1로 마이그레이션

• 스크립트 엔드포인트는 이제 기본적으로 비활성화됩니다. /run_script_inline 또는 /run_ghidra_script에 의존했다면 GHIDRA_MCP_ALLOW_SCRIPTS=1을 내보내십시오. 이는 의도된 호환성 변경입니다; 이전 기본값은 안전하지 않았습니다.
• 로컬호스트 전용 배포는 변경이 필요하지 않습니다. 인증, 바인딩 거부 및 경로 루트 검사는 모두 선택 사항입니다.

❓ 문제 해결

"GhidraMCP" 메뉴가 Tools에 나타나지 않음

원인: 플러그인이 활성화되지 않았거나 잘못 설치되었습니다.

해결 방법:

1. 확장 프로그램이 설치되었는지 확인: File > Install Extensions — GhidraMCP가 목록에 표시되어야 합니다.
2. 플러그인 활성화: File > Configure > Configure All Plugins > GhidraMCP (체크박스 선택)
3. 설치/활성화 후 Ghidra 다시 시작

서버 응답 없음 / 연결 거부됨

원인: 서버가 시작되지 않았거나 잘못된 포트입니다.

해결 방법:

1. 서버를 시작했는지 확인: Tools > GhidraMCP > Start MCP Server
2. 설정된 포트 확인: Edit > Tool Options > GhidraMCP HTTP Server
3. 포트가 사용 중인지 확인: ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. Ghidra 콘솔에서 오류를 찾으세요: Window > Console

pip install가 error: externally-managed-environment로 실패하는 경우

원인: PEP 668. Debian 계열 배포판(Debian 12+, Kali, Ubuntu 23.04+) 시스템 Python을 외부 관리로 표시하므로, 전역 pip install이 apt로 관리되는 패키지를 보호하기 위해 차단됩니다.

해결 방법: 가상 환경을 사용하세요 — --break-system-packages는 절대 사용하지 마세요. 권장 경로는 uv이며, 프로젝트-로컬 .venv를 자동으로 관리합니다:```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

또는 클래식한 venv:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger가 pybag 또는 comtypes에 대해 ModuleNotFoundError로 실패합니다.

원인: 독립 실행형 디버거 서버는 기본적으로 설치되지 않는 선택적 Windows 전용 Python 종속성을 사용합니다.

해결 방법:```text uv sync --group debugger uv run python -m debugger

전역 Python과 프로젝트 venv가 모두 있는 경우, 동일한 인터프리터에 설치하고 실행해야 합니다.

### 500 내부 서버 오류

**원인:** 서버 측 예외로, 주로 누락된 프로그램 데이터로 인해 발생합니다.

**해결 방법:**
1. CodeBrowser에 바이너리가 로드되었는지 확인하세요.
2. 먼저 자동 분석 실행: **Analysis > Auto Analyze**
3. Ghidra 콘솔(**Window > Console**)에서 Java 예외 확인
4. 일부 작업은 완전히 분석된 바이너리가 필요합니다.

### 404 찾을 수 없음 오류

**원인:** 엔드포인트가 존재하지 않거나 URL이 잘못되었습니다.

**해결 방법:**
1. 엔드포인트 존재 확인: `curl http://127.0.0.1:8089/get_version`
2. 엔드포인트 이름의 오타 확인
3. 올바른 HTTP 메서드(GET 대 POST)를 사용하고 있는지 확인

### Python Ghidra 스크립트가 "No script provider found" 오류로 실패

**원인:** Ghidra 12.1.2에서는 Jython 지원이 기본적으로 활성화되지 않습니다. `.py` 스크립트는 번들된 Jython 확장이 필요합니다. Python 3 스크립트는 Ghidra Script Manager 대신 PyGhidra를 사용해야 합니다.

**해결 방법:**
1. Ghidra Front End에서 **File > Install Extensions**를 엽니다.
2. **Jython**을 체크하고 Ghidra를 재시작한 후 Script Manager를 새로고침합니다.
3. 새로운 자동화의 경우 Java Ghidra 스크립트 또는 PyGhidra를 선호하세요.

### Install Extensions에 확장이 나타나지 않음

**원인:** JAR 파일이 잘못된 위치에 있습니다.

**해결 방법:**
1. 수동 설치 위치: `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. 또는 **File > Install Extensions > Add**를 사용하여 ZIP 파일을 선택하세요.
3. JAR/ZIP이 사용 중인 Ghidra 버전용으로 빌드되었는지 확인하세요.

### "Ghidra dependencies not found" 오류로 빌드 실패

**원인:** Ghidra JAR이 로컬 Maven 저장소에 설치되지 않았습니다.

**해결 방법:**```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 프로덕션 성능

• MCP 도구: 271개 도구 완전 구현
• 속도: 대부분 작업에 대해 1초 미만 응답
• 효율성: 배치 작업을 통해 API 호출 93% 감소
• 신뢰성: 전부 아니면 전무(all-or-nothing) 의미 체계의 원자적 트랜잭션
• AI 워크플로: 수백 개의 실제 함수에서 정제된 검증된 문서 프롬프트
• 배포: 자동 버전 인식 배포 스크립트

🛠️ API 참조

271개의 MCP 도구가 HTTP 엔드포인트로 제공되며, 카탈로그 카테고리별로 그룹화되었습니다. python -m tools.gen_readme_api_reference --write에 의해 tests/endpoints.json에서 생성되었습니다. 런타임 시 /mcp/schema의 라이브 스키마가 권위를 갖습니다. 사용 패턴: docs/prompts/TOOL_USAGE_GUIDE.md.

프로그램 및 세션 관리

• analysis_status - 열려 있는 프로그램의 자동 분석 상태 가져오기
• close_program - 프로젝트 경로 또는 이름으로 열려 있는 프로그램 닫기
• create_property_map - 주소로 키가 지정된 타입 값 저장을 위한 사용자 속성 맵 생성
• delete_property_map - 사용자 속성 맵과 그 안의 모든 값 삭제
• exit_ghidra - 저장 후 Ghidra 종료
• get_address_spaces - 프로그램의 모든 물리적 및 오버레이 주소 공간 나열 (오버레이는 is_overlay 플래그와 overlayed_space 이름 포함)
• get_current_program_info - 현재 프로그램 정보 가져오기
• get_language_metadata - 프로그램의 언어 설명 덤프: 주소 공간, 레지스터, 기본 심볼, 엔디언, 포인터 크기 (이슈 #192)
• get_program_options - 프로그램 옵션 그룹의 모든 옵션을 타입, 현재 값, 기본값, 설명과 함께 읽기
• get_property - 속성 맵의 주소에 저장된 값 읽기
• import_file - 디스크에서 현재 Ghidra 프로젝트로 바이너리 파일 가져오기 및 열기
• list_open_programs - 열려 있는 프로그램 나열

프로젝트 조직

• create_folder - 프로젝트에 폴더 생성
• delete_file - 프로젝트에서 파일 삭제
• delete_project - Ghidra 프로젝트 삭제
• list_projects - 사용 가능한 Ghidra 프로젝트 나열
• move_file - 파일을 다른 프로젝트 폴더로 이동
• move_folder - 폴더를 다른 위치로 이동
• project_info - 실행 중인 도구 및 열린 프로그램을 포함한 상세 프로젝트 정보 가져오기

헤드리스 프로젝트 및 프로그램 수명 주기

독립형 헤드리스 서버(GhidraMCPHeadlessServer)에서 사용 가능합니다.

• archive_project - 현재 열려 있는 프로젝트를 Ghidra 네이티브 .gar 파일로 아카이브
• checkin_program - 열려 있는 프로그램을 새 버전으로 공유 Ghidra 서버에 체크인
• close_project - 현재 열려 있는 프로젝트 닫기
• create_project - 새 Ghidra 프로젝트 생성
• export_program - 열려 있거나 프로젝트에 있는 프로그램을 Ghidra Zip 파일(.gzf)로 내보내기
• get_project_info - 현재 열려 있는 프로젝트에 대한 정보 가져오기
• import_program - Ghidra Zip 파일(.gzf)을 현재 열려 있는 프로젝트에 target_folder(기본값 '/') 아래 새 DomainFile로 가져오기
• load_program - 분석을 위해 헤드리스 서버에 바이너리 파일 로드
• load_program_from_project - Ghidra 프로젝트에서 프로그램 로드 (헤드리스)
• open_project - 기존 Ghidra 프로젝트(.gpr 파일 또는 디렉터리) 열기
• restore_project - Ghidra .gar 아카이브를 parent_dir/project_name의 새 디스크 프로젝트로 복원

리스팅 및 열거

• list_bookmarks - 북마크 나열
• list_calling_conventions - 사용 가능한 호출 규약 나열
• list_classes - 네임스페이스/클래스 이름 나열
• list_data_items - 정의된 데이터 나열
• list_data_items_by_xrefs - 교차 참조 수로 정렬된 데이터 나열
• list_exports - 내보낸 심볼 나열
• list_external_locations - 외부 위치 나열
• list_functions - 주소와 함께 함수 나열
• list_functions_enhanced - 메타데이터와 함께 함수 나열
• list_globals - 전역 변수 나열
• list_imports - 가져온 심볼 나열
• list_methods - 페이지네이션과 함께 모든 함수 이름 나열
• list_namespaces - 모든 네임스페이스 나열

컨텍스트 및 조회

• get_current_address - 커서 주소 가져오기 (GUI 전용)
• get_current_function - 커서 위치의 함수 가져오기 (GUI 전용)
• get_current_selection - CodeBrowser 리스팅에서 강조 표시된 주소 범위 가져오기 (GUI 전용)
• get_entry_points - 프로그램 진입점 가져오기
• get_enum_values - 열거형 값 가져오기
• get_external_location - 외부 위치 세부 정보 가져오기
• get_full_call_graph - 전체 호출 그래프 가져오기
• get_function_by_address - 주소의 함수 가져오기
• get_function_call_graph - 호출 그래프 가져오기
• get_function_callees - 호출된 함수 가져오기
• get_function_callers - 호출하는 함수 가져오기
• get_function_count - 로드된 프로그램의 함수 수 반환

검색

• find_similar_functions - 유사한 함수 찾기
• search_byte_patterns - 바이트 패턴 검색
• search_data_types - 데이터 타입 검색
• search_functions - 이름으로 함수 검색
• search_functions_enhanced - 고급 함수 검색
• search_strings - 정규식/부분 문자열 패턴으로 정의된 문자열 검색

디컴파일 및 디스어셈블

• decompile_function - 함수 디컴파일
• disassemble_bytes - 바이트 범위 디스어셈블
• disassemble_function - 함수 디스어셈블
• force_decompile - 새로고침 디컴파일 강제 실행

함수 태그, 변수 및 속성

• add_function_tag - 함수에 하나 이상의 태그 첨부
• batch_add_function_tags - 한 트랜잭션으로 여러 함수에 태그 첨부
• batch_remove_function_tags - 한 트랜잭션으로 여러 함수에서 태그 분리
• clear_flow_and_repair - 시드 범위에서 Ghidra의 GUI 'Clear Flow and Repair' 작업 실행: 시드에서 도달 가능한 명령어 흐름을 지운 후 함수 본문을 수리하고 유지된 흐름을 재디스어셈블 (ClearFlowAndRepairCmd, clear_data=false, clear_labels=false, repair=true)
• create_function_tag - 선택적 주석과 함께 프로그램 전체 함수 태그 정의 생성
• delete_function_tag - 프로그램 전체 함수 태그 정의 삭제
• get_function_tags - 특정 함수에 할당된 모든 태그 나열
• list_class_members - C++ 클래스의 멤버 함수 나열
• list_function_tags - 사용 횟수와 함께 모든 프로그램 전체 함수 태그 정의 나열
• remove_function_tag - 함수에서 하나 이상의 태그 분리
• search_functions_by_tag - 지정된 태그가 첨부된 모든 함수 나열
• - 이름으로 디컴파일러(고수준) 변수 또는 매개변수 타입 설정

교차 참조

• add_memory_reference - 자동 분석기가 추론할 수 없는 두 메모리 주소 간 사용자 정의 교차 참조 생성 (런타임에 채워지는 포인터 테이블, vtable, 늦게 바인딩된 함수 포인터, 누락된 점프/스위치 테이블)
• get_bulk_xrefs - 여러 주소에 대한 교차 참조 가져오기
• get_function_xrefs - 함수 교차 참조 가져오기
• get_xrefs_from - 주소에서 나가는 참조 가져오기
• get_xrefs_to - 주소로 들어오는 참조 가져오기
• remove_reference - 한 주소에서 다른 주소로의 메모리 교차 참조 제거 — add_memory_reference의 역연산

데이터 타입 및 구조체

• add_struct_field - 구조체 필드 추가
• analyze_global_completeness - 예산 제약하에 0-100 척도로 전역 변수의 문서 완전성 점수 매기기 — analyze_function_completeness의 데이터 주소 유사체
• apply_data_type - 데이터 타입 적용
• audit_global - 전역 변수의 문서 상태 감사
• audit_globals_in_function - 한 번의 호출로 함수 내에서 참조된 모든 전역 변수 감사
• batch_set_variable_types - 여러 변수 타입 설정
• clone_data_type - 데이터 타입 복제
• create_array_type - 배열 타입 생성
• create_data_type_category - 데이터 타입 카테고리 생성
• create_enum - 열거형 생성
• create_function_signature - 함수 시그니처 타입 생성
• create_pointer_type - 포인터 타입 생성

이름 변경 및 레이블

• batch_create_labels - 여러 레이블 생성
• batch_delete_labels - 여러 레이블 삭제
• batch_rename_function_components - 함수 구성 요소 배치 이름 변경
• create_label - 레이블 생성
• delete_label - 주소의 레이블 삭제
• rename_data - 데이터 심볼 이름 변경
• rename_external_location - 외부 위치 이름 변경
• rename_function - 이름으로 함수 이름 변경
• rename_function_by_address - 주소로 함수 이름 변경
• rename_global_variable - 전역 변수 이름 변경
• rename_label - 레이블 이름 변경
• rename_or_label - 레이블 이름 변경 또는 생성
• rename_variable - 함수 내 변수 이름 변경

주석 및 북마크

• batch_set_comments - 여러 주석 설정
• clear_function_comments - 함수의 모든 주석 지우기
• delete_bookmark - 북마크 삭제
• get_comment - 모든 주소(데이터 주소 포함)에서 리스팅 주석(plate/pre/eol/post/repeatable) 가져오기 (get_plate_comment는 함수가 필요함)
• get_plate_comment - 플레이트 주석 가져오기
• set_bookmark - 북마크 설정
• set_comment - 모든 주소(데이터 주소 포함)에 지정된 종류(plate/pre/eol/post/repeatable)의 리스팅 주석 설정
• set_decompiler_comment - PRE_COMMENT 설정
• set_disassembly_comment - EOL_COMMENT 설정
• set_plate_comment - 플레이트 주석 설정

분석

• analyze_api_call_chains - API 호출 체인 분석
• analyze_call_graph - 함수 호출 그래프 패턴 분석
• analyze_control_flow - 제어 흐름 분석
• analyze_data_region - 데이터 영역 분석
• analyze_dataflow - 함수를 통한 값 전파 추적 (PCode 그래프, 순방향/역방향)
• analyze_for_documentation - 복합 RE 문서 분석 (디컴파일 + 분류 + 변수 + 완전성)
• analyze_function_complete - 포괄적인 단일 호출 함수 분석
• analyze_function_completeness - 문서 완전성 분석
• analyze_struct_field_usage - 구조체 필드 사용 분석
• apply_data_classification - 데이터 분류 적용
• batch_analyze_completeness - 여러 함수의 완전성 배치 분석
• batch_apply_documentation - 한 번의 호출로 함수에 모든 문서 적용

교차 바이너리 문서 및 아카이브

• archive_ingest_function - 단일 함수의 문서를 교차 버전 아카이브(bsim Postgres의 re_kb.functions)에 수집
• archive_ingest_program - 프로그램의 모든 함수를 교차 버전 문서 아카이브에 대량 수집
• batch_string_anchor_report - 소스 파일 문자열과 해당 FUN_* 함수의 보고서
• bulk_fuzzy_match - 대량 교차 바이너리 함수 매칭
• find_similar_functions_fuzzy - 교차 바이너리 퍼지 함수 매칭
• merge_program_documentation - 대량 병합: 모든 RE 문서(함수 이름, 시그니처, 플레이트 주석, EOL/PRE/POST 명령어 주석, 기본값이 아닌 레이블 및 전역 심볼)를 일치하는 주소에서 한 프로그램에서 다른 프로그램으로 복사

유틸리티 및 문서 전송

• apply_function_documentation - 함수 문서 적용
• check_connection - 상태 확인 엔드포인트
• compare_programs_documentation - 프로그램 간 문서 비교
• convert_number - 숫자 간 변환
• diff_functions - 두 함수 차이 비교
• find_undocumented_by_string - 문자열을 참조하는 미문서 함수 찾기
• get_bulk_function_hashes - 대량 함수 해시 가져오기
• get_function_documentation - 함수 문서 내보내기
• get_function_hash - 함수 해시 가져오기
• get_function_signature - 함수 특징 시그니처 가져오기
• get_metadata - 프로그램 메타데이터 가져오기
• get_version - 플러그인 버전 가져오기
• - 헤드리스 서버 상태 확인 엔드포인트

에뮬레이션

• emulate_function - 제어된 레지스터/메모리 입력으로 단일 함수 에뮬레이션
• emulate_hash_batch - API 해시 해결을 위한 무차별 대입

스크립팅

• run_ghidra_script - 출력 캡처와 함께 스크립트 실행
• run_script_inline - 인라인 스크립트 코드 실행

Ghidra 서버 및 버전 관리

• server_admin_set_permissions - 리포지토리에 사용자 권한 설정
• server_admin_terminate_all_checkouts - 폴더 내 모든 체크아웃을 재귀적으로 종료
• server_admin_terminate_checkout - 단일 파일의 모든 체크아웃 종료
• server_admin_users - 서버의 모든 사용자 나열
• server_authenticate - 프로그래매틱 인증을 위한 서버 자격 증명 등록
• server_checkouts - 폴더 내 체크아웃된 모든 파일 나열, 서버 측 체크아웃 포함
• server_connect - Ghidra 서버에 연결
• server_disconnect - Ghidra 서버 연결 해제
• server_repositories - 연결된 서버의 리포지토리 나열
• server_repository_create - 서버에 새 리포지토리 생성
• server_repository_file - 서버 리포지토리에서 파일 정보 가져오기
• server_repository_files - 서버 리포지토리 폴더의 파일 나열

디버거 (Ghidra TraceRmi — GUI 전용)

브리지의 WinDbg 디버거 프록시가 활성화된 Windows 호스트(GHIDRA_DEBUGGER_URL)에서는 충돌하는 이름에 _2 접미사가 붙습니다 (예: debugger_status_2).

• debugger_dynamic_to_static - 현재 트레이스의 런타임 동적 주소를 정적 Ghidra 프로그램 주소로 변환
• debugger_interrupt - 실행 중인 대상 중단 (브레이크 인)
• debugger_launch - Ghidra의 Trace RMI 디버거 실행기를 통해 실행 파일 실행
• debugger_launch_offers - 현재 프로그램에 사용 가능한 디버거 실행/연결 옵션 나열
• debugger_list_breakpoints - 현재 트레이스의 모든 중단점 나열
• debugger_modules - 디버그된 프로세스에 로드된 모듈(DLL/EXE) 나열
• debugger_read_memory - 디버그된 프로세스에서 메모리 읽기
• debugger_registers - 현재 디버그 트레이스 스냅샷에서 CPU 레지스터 읽기
• debugger_remove_breakpoint - 주소의 중단점 제거
• debugger_resume - 디버그된 프로세스 실행 재개
• debugger_set_breakpoint - 트레이스의 주소에 소프트웨어 실행 중단점 설정
• debugger_stack_trace - 현재 스레드의 호출 스택 역추적 가져오기

시스템

• prompt_policy - 범위가 지정된 자동화 프롬프트 처리를 일시적으로 활성화, 비활성화 또는 쿼리

브리지 정적 도구Defined in the Python bridge itself (instance discovery, tool-group management); always available even before a Ghidra connection. The bridge also proxies 22 debugger_* WinDbg tools when GHIDRA_DEBUGGER_URL points at the standalone debugger server.

• check_tools - 현재 등록되어 호출 가능한 도구를 보고합니다.
• connect_instance - 브릿지를 특정 Ghidra 인스턴스에 연결합니다.
• import_file - 디스크에서 현재 프로젝트로 바이너리를 가져와 엽니다.
• list_instances - 실행 중인 Ghidra MCP 인스턴스를 검색합니다 (UDS + TCP 포트 스캔).
• list_tool_groups - 도구 그룹과 해당 로드 상태를 나열합니다.
• load_tool_group - 도구 그룹의 동적 도구를 MCP 클라이언트에 등록합니다.
• search_tools - 전체 도구 카탈로그를 키워드로 검색합니다.
• unload_tool_group - 도구 그룹의 동적 도구 등록을 해제합니다.

CHANGELOG.md에서 버전 기록을 확인하세요.

🏗️ 아키텍처```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### 구성 요소

- **python/bridge_mcp_ghidra/** — MCP 프로토콜을 HTTP 호출(225개 카탈로그 항목)로 변환하는 Python MCP 서버 패키지 (`ghidra-mcp-bridge` 휠로 제공, `bridge-mcp-ghidra` 콘솔 스크립트)
- **GhidraMCP.jar** — HTTP(175개 GUI 엔드포인트)를 통해 분석 기능을 제공하는 Ghidra 플러그인
- **GhidraMCPHeadlessServer** — 독립형 헤드리스 서버 — 183개 엔드포인트, GUI 불필요
- **ghidra_scripts/** — 일반적인 작업을 위한 자동화 스크립트 모음

## 🔧 개발

### 소스에서 빌드하기```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

현재 공식 빌드 시스템은 Maven입니다. tools.setup, VS Code 작업, 문서화된 배포 흐름은 모두 pom.xml을 통해 빌드하고 아티팩트를 target/에 기록합니다. build.gradle은 직접 Ghidra/Gradle 사용자를 위한 수동 대체 수단으로 저장소에 남아 있지만, 기본 경로는 아닙니다.

명령어 참조

대부분의 명령어에서 사용하는 공통 플래그:

배포 테스트 계층은 옵트인 방식입니다. 벤치마크 계층이 활성 Ghidra 프로젝트에서 Benchmark.dll과 BenchmarkDebug.exe를 가져오거나 초기화할 수 있기 때문입니다. 릴리스를 준비하기 전에 --test release를 사용하거나, 기기에서 모든 배포 시 라이브 벤치마크 회귀 테스트를 실행하려면 로컬 .env에 GHIDRA_MCP_DEPLOY_TESTS=release를 설정하세요. Testing and Release Regression을 참조하세요.```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### 프로젝트 구조```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

라이브러리 의존성

Ghidra JAR은 컴파일 전에 로컬 Maven 저장소(~/.m2/repository)에 설치되어야 합니다. 이것은 기기당 한 번 설정이며, Ghidra 버전이 변경될 때 다시 해야 합니다. -Deploy는 이제 기본적으로 이를 자동으로 설치합니다.

이 도구는 다음 사이의 버전 일관성을 강제합니다:

• pom.xml (ghidra.version)
• --ghidra-path 버전 세그먼트 (예: ghidra_12.1.2_PUBLIC)

이들이 일치하지 않으면 배포가 명확한 오류와 함께 즉시 실패합니다.

문제 해결: 버전 불일치

버전 불일치 오류가 발생하면 두 값을 일치시키십시오:

1. pom.xml → ghidra.version
2. --ghidra-path 버전 세그먼트 (ghidra_X.Y.Z_PUBLIC)

그런 다음 다시 실행하세요:```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

No Markdown content provided for translation.```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

Required Libraries (14 JARs, ~37MB):

Note: Libraries are NOT included in the repository (see .gitignore). You must install them from your Ghidra installation before building.

Automation entry point:

• python -m tools.setup is the supported setup/build/deploy/versioning interface
• use ensure-prereqs, build, deploy, preflight, clean-all, and bump-version directly
• these commands currently use Maven as the canonical Java build backend

Development Features

• Automated Deployment: Version-aware deployment script
• Batch Operations: Reduces API calls by 93%
• Atomic Transactions: All-or-nothing semantics
• Comprehensive Logging: Debug and trace capabilities

📚 Documentation

Core Documentation

• Documentation Index - Complete documentation navigation
• Project Structure - Project organization guide
• Testing and Release Regression - Local tests, CI, live Ghidra regression, and release gates
• Naming Conventions - Code naming standards
• Hungarian Notation - Variable naming guide

AI Workflow Prompts

• Function Documentation V5 — Primary workflow: 7-step process with Hungarian notation, type auditing, and verification scoring
• Batch Documentation V5 — Parallel subagent dispatch for multi-function processing
• Orphaned Code Discovery — Automated scanner for undiscovered functions
• Data Type Investigation — Systematic structure discovery
• Cross-Version Matching — Hash-based function matching
• Quick Start Prompt — Simplified beginner workflow
• All Prompts — Complete prompt index

Release History

• Complete Changelog - All version release notes
• Release Notes - Detailed release documentation

🐳 Headless Server (Docker)

GhidraMCP includes a headless server mode for automated analysis without the Ghidra GUI.

Quick Start with Docker```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### 헤드리스 API 워크플로우```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

주요 헤드리스 엔드포인트

구성

Docker 환경 변수:

• GHIDRA_MCP_PORT - 서버 포트 (기본값: 8089)
• GHIDRA_MCP_BIND_ADDRESS - 바인드 주소 (Docker 기본값: 0.0.0.0)
• JAVA_OPTS - JVM 옵션 (기본값: -Xmx4g -XX:+UseG1GC)

🤝 기여하기

자세한 기여 가이드라인은 CONTRIBUTING.md를 참조하세요.

빠른 시작

1. 저장소 포크하기
2. 기능 브랜치 생성 (git checkout -b feature/amazing-feature)
3. 변경 사항 빌드 및 테스트 (mvn clean package assembly:single -DskipTests 또는 GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. 필요에 따라 문서 업데이트
5. 변경 사항 커밋 (git commit -m 'Add amazing feature')
6. 브랜치에 푸시 (git push origin feature/amazing-feature)
7. Pull Request 열기

📄 라이선스

이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🏆 프로덕션 상태

버전 기록 및 릴리스 노트는 CHANGELOG.md를 참조하세요.

🙏 감사의 말

이 프로젝트는 2025년 8월 LaurieWired/GhidraMCP에서 파생되었으며, 이후 상당 부분 재작성 및 확장되었습니다. 시작점이 된 LaurieWired의 원본 작업에 감사드립니다. 라이선스 표시는 NOTICE를 참조하세요.

👥 기여자

이 프로젝트는 헌신적인 기여자들의 작업 덕분에 발전했습니다:

핵심 기여자

@heeen — 주요 기여 사항:

• 교차 바이너리 비교를 위한 퍼지 함수 매칭 및 구조적 diff (#13)
• 스크립트 실행 개선 및 버그 수정 (#12)
• 새 API 엔드포인트: save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• 아키텍처 비전: 어노테이션 기반 설계, UDS 전송, Python 브리지 최적화 제안

@huehuehuehueing — 주요 기여 사항:

• 주소 공간 접두사 지원 — 전체 엔드포인트 표면의 주소 파싱에 <space>:<hex> 구문(예: mem:1000, code:ff00) 추가, 임베디드 펌웨어와 같은 다중 공간 대상 지원 (#84, #65 종료)

• 선택적 program 매개변수 + 필수 매개변수 스키마 수정 — 모든 엔드포인트에서 program을 합리적인 currentProgram 폴백으로 선택적 처리, 카탈로그가 상속한 여러 필수-선택 스키마 버그 수정 (#92)

• #44 시드 (데이터 타입 / 열거형 도구) — v5.0 열거형 + 구조체 강제 레이어의 동기가 된 이슈

• Ghidra 팀 - 놀라운 리버스 엔지니어링 플랫폼을 제공해 주셔서 감사합니다

• Model Context Protocol - 표준화된 AI 통합 프레임워크를 제공해 주셔서 감사합니다

• 기여자 - 테스트, 피드백 및 개선에 감사드립니다

🔗 관련 프로젝트

• re-universe — 대규모 바이너리 유사성 분석을 위한 Ghidra BSim PostgreSQL 플랫폼. AI 기반 리버스 엔지니어링 워크플로우를 위해 GhidraMCP와 완벽하게 페어링됩니다.
• cheat-engine-server-python — 동적 메모리 분석 및 디버깅을 위한 MCP 서버.

엔터프라이즈급 안정성과 포괄적인 바이너리 분석 기능을 갖춘 프로덕션 배포 준비 완료.