Python 명령줄 Ghidra MCP
**pyghidra-mcp**는 강력한 소프트웨어 리버스 엔지니어링(SRE) 제품군인 Ghidra의 모든 분석력을 지능형 에이전트와 LLM 기반 도구의 세계로 가져오는 명령줄 Model Context Protocol(MCP) 서버입니다.
pyghidra와 jpype를 사용하여 Ghidra의 ProgramAPI 및 FlatProgramAPI를 Python에 연결한 다음, 해당 기능을 Model Context Protocol을 통해 노출합니다.
MCP는 언어 모델, 개발 도구(VS Code 등), 자율 에이전트가 구조화된 컨텍스트에 접근하고 도구를 호출하며 지능적으로 협업할 수 있게 해주는 통합 인터페이스입니다. MCP를 강력한 분석 도구와 LLM 생태계 사이의 다리로 생각하면 됩니다.
pyghidra-mcp를 사용하면 Ghidra는 지능형 백엔드가 됩니다. 컨텍스트가 풍부한 쿼리에 응답하고, 심층 리버스 엔지니어링 작업을 자동화하며, AI 지원 워크플로우에 통합될 준비가 되어 있습니다.
pyghidra-mcp는 이제 두 가지 작동 모드를 지원합니다:
headless 모드--gui 모드 - pyghidra-mcp를 통해 Ghidra를 실행하고 실행 중인 GUI와 실시간 프로그램 상태를 공유합니다.[!NOTE] 이 베타 프로젝트는 활발히 개발 중입니다. 피드백, 버그 보고, 기능 요청, 코드 기여를 환영합니다.
네, 원조 ghidra-mcp도 훌륭합니다. 하지만 pyghidra-mcp는 다른 접근 방식을 취합니다:
--gui로 Ghidra를 실행할 수 있습니다.이 프로젝트는 로컬 개발, headless 환경, 테스트 가능한 워크플로우에 최적화된 Python 우선 경험을 제공합니다.
flowchart LR subgraph Clients["Clients"] Agent["MCP host / agent"] Cli["pyghidra-mcp-cli"] User["Ghidra user"] end
subgraph Process["pyghidra-mcp process"]
Transport["stdio or streamable-http"]
Tools["MCP tools"]
Context["PyGhidra context"]
end
Project["Ghidra project<br/>.gpr / .rep"]
Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]
Agent -->|"stdio or HTTP"| Transport
Cli -->|"HTTP only"| Transport
Transport --> Tools
Tools --> Context
Context --> Project
Context --> Artifacts
Context -.-> Gui
User -.-> Gui
Gui -.-> Project
### 모드 선택```mermaid
flowchart TD
Start["What do you need?"]
Start --> Headless["Agent or automation only"]
Start --> GuiNeed["Live Ghidra GUI control"]
Start --> Terminal["Interactive terminal client"]
Headless --> Stdio["pyghidra-mcp -t stdio<br/>or -t streamable-http"]
GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]
stdio를 사용하고, 여러 클라이언트가 동일한 장기 실행 Ghidra 프로젝트를 필요로 할 때는 streamable-http를 사용하세요.pyghidra-mcp는 Ghidra를 실행하고 프로젝트를 열어 동일한 JVM에서 CodeBrowser를 제어하는 추가 도구를 노출합니다.pyghidra-mcp-cli는 HTTP 클라이언트입니다. 먼저 streamable-http 서버를 시작한 다음, 실행 중인 서버를 대상으로 터미널 명령을 실행하세요.subgraph Transports
Stdio["stdio"]
Http["streamable-http"]
Sse["sse legacy"]
end
subgraph Server["pyghidra-mcp server"]
FastMcp["FastMCP tool server"]
Context["PyGhidra context"]
Indexing["background analysis and Chroma indexing"]
subgraph Tools["MCP tools"]
Analysis["decompile, xrefs, bytes, callgraph"]
Search["symbols, strings, code"]
ProjectOps["import, delete, metadata, list binaries"]
Edits["rename function, rename variable, set type, set prototype, set comment"]
GuiOnly["GUI only: open program, goto, list open programs, set current program"]
end
end
subgraph GhidraRuntime["Ghidra runtime"]
PyGhidra["pyghidra"]
Jpype["JPype shared JVM"]
Project["Ghidra project"]
Programs["program databases"]
CodeBrowser["Ghidra GUI / CodeBrowser"]
end
Agent --> Stdio
Agent --> Http
Automation --> Stdio
Automation --> Http
Automation --> Sse
Cli --> Http
Stdio --> FastMcp
Http --> FastMcp
Sse --> FastMcp
FastMcp --> Context
Context --> PyGhidra
PyGhidra --> Jpype
Jpype --> Project
Project --> Programs
Context --> Indexing
Indexing --> Search
FastMcp --> Tools
Tools --> Context
GuiOnly -.-> CodeBrowser
Context -.-> CodeBrowser
</details>
## 목차
- [PyGhidra-MCP - Ghidra 모델 컨텍스트 프로토콜 서버](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [개요](#overview)
- [또 다른 Ghidra MCP?](#yet-another-ghidra-mcp)
- [설정 다이어그램](#setup-diagrams)
- [구성 요소가 연결되는 방식](#how-the-pieces-connect)
- [모드 선택](#choosing-a-mode)
- [목차](#contents)
- [시작하기](#getting-started)
- [에이전트에 최적화](#optimized-for-agents)
- [CLI 클라이언트](#cli-client)
- [설치](#installation)
- [CLI 빠른 시작](#quick-start-with-cli)
- [프로젝트 생성, 관리 및 기존 프로젝트 열기](#project-creation-management-and-opening-existing-projects)
- [새 프로젝트 만들기](#creating-new-projects)
- [자체 포함 프로젝트 구조](#self-contained-project-structure)
- [기본 프로젝트 생성](#basic-project-creation)
- [사용자 지정 프로젝트 생성](#custom-project-creation)
- [여러 관련 프로젝트 만들기](#creating-multiple-related-projects)
- [기존 Ghidra 프로젝트 열기](#opening-existing-ghidra-projects)
- [.gpr 파일로 열기](#opening-by-gpr-file)
- [GUI 모드](#gui-mode)
- [시작 기본값 및 대형 프로젝트](#startup-defaults-and-large-projects)
- [개발](#development)
- [설정](#setup)
- [테스트 및 품질](#testing-and-quality)
- [API](#api)
- [도구](#tools)
- [일괄 작업](#batch-operations)
- [읽기 / 분석 도구](#read--analysis-tools)
- [프로젝트 작업](#project-operations)
- [편집 / 변형 도구](#edit--mutation-tools)
- [GUI 제어 도구 (`--gui` 전용)](#gui-control-tools---gui-only)
- [사용법](#usage)
- [Docker로 바이너리 매핑](#mapping-binaries-with-docker)
- [OpenWeb-UI 및 MCPO와 함께 사용하기](#using-with-openweb-ui-and-mcpo)
- [`uvx` 사용](#with-uvx)
- [Docker 사용](#with-docker)
- [표준 입력/출력 (stdio)](#standard-inputoutput-stdio)
- [Python](#python)
- [Docker](#docker)
- [Streamable HTTP](#streamable-http)
- [Python](#python-1)
- [Docker](#docker-1)
- [서버 전송 이벤트 (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-2)
- [통합](#integrations)
- [Claude Desktop](#claude-desktop)
- [영감](#inspiration)
- [기여, 커뮤니티, 그리고 소스에서 실행하기](#contributing-community-and-running-from-source)
- [기여자 워크플로우](#contributor-workflow)
## 시작하기
Python 패키지를 CLI 명령으로 실행하려면 [`uv`](https://docs.astral.sh/uv/guides/tools/)를 사용합니다:```bash
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default
MCP에서 라이브 Ghidra GUI를 시작하고 제어하려면 --gui를 streamable-http와 함께 사용하십시오:```bash
uvx pyghidra-mcp
--gui
--transport streamable-http
--host 127.0.0.1
--port 8000
--project-path /absolute/path/to/ghidra-projects
--project-name my_project
> [!IMPORTANT]
> `--gui`는 `pyghidra-mcp`를 통해 Ghidra를 실행합니다. 이미 실행 중인 외부 Ghidra 인스턴스에는 연결되지 않습니다.
또는 [Docker 컨테이너](https://ghcr.io/clearbluejar/pyghidra-mcp)로 실행합니다:```bash
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio
pyghidra-mcp는 MCP 표면을 의도적으로 좁게 유지하여 에이전트 클라이언트가 도구 발견 및 인수 선택에 더 적은 토큰을 사용하도록 합니다.
open_program_in_gui, list_open_programs, set_current_program, goto 같은 GUI 전용 컨트롤은 서버가 --gui로 시작된 경우에만 노출됩니다.pyghidra-mcp-cli가 일반적인 편집 및 분석 워크플로를 위한 그룹화된 명령과 함께 HTTP를 통한 직접 명령줄 클라이언트를 제공합니다.이렇게 하면 기본 서버가 헤드리스 세션에서 불필요한 도구 표면이나 GUI 전용 컨트롤을 노출하지 않으면서 LLM 에이전트, IDE 통합 및 자동화에 사용할 수 있습니다.
더 대화형인 명령줄 환경을 위해 별도의 pyghidra-mcp-cli 패키지를 사용할 수 있습니다. 이 패키지는 실행 중인 pyghidra-mcp 서버와 상호작용하기 위한 사용자 친화적인 인터페이스를 제공합니다.
uv를 사용하여 CLI 클라이언트를 설치합니다(권장):```bash
uvx pyghidra-mcp-cli
또는 pip로 설치:```bash
pip install pyghidra-mcp-cli
2. **CLI 사용** (다른 터미널에서):```bash
# List available binaries
pyghidra-mcp-cli list binaries
# Decompile a function
pyghidra-mcp-cli decompile --binary ls main
# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs
# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10
[!NOTE] CLI는 각 명령에 대해 새 Ghidra 프로세스를 시작할 때 발생하는 10~60초의 시작 오버헤드를 피하기 위해 HTTP를 통해 pyghidra-mcp에 연결합니다. 전체 문서는 CLI README를 참조하세요.
워크플로에 따라 여러 가지 방법으로 새 프로젝트를 만들 수 있습니다:
pyghidra-mcp는 각 프로젝트가 자체 Ghidra 프로젝트와 pyghidra-mcp 아티팩트를 갖는 자체 포함 프로젝트 구조를 생성합니다. 이는 완전한 격리와 쉬운 프로젝트 관리를 보장합니다.
pyghidra-mcp
$ tree pyghidra_mcp_projects/ pyghidra_mcp_projects/ ├── my_project.gpr ├── my_project-pyghidra-mcp │ ├── chromadb │ └── gzfs └── my_project.rep
#### 커스텀 프로젝트 생성```bash
# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis
$ tree ~/analysis/
/home/vscode/analysis/
└── malware_study
├── malware_analysis.gpr
├── malware_analysis-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── malware_analysis.rep
mkdir ~/reverse_engineering_workspace
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis
### 기존 Ghidra 프로젝트 열기
기존 Ghidra 프로젝트(`.gpr` 파일)가 있다면 `pyghidra-mcp`로 직접 열 수 있습니다:
#### .gpr 파일로 열기```bash
# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr
# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)
GUI 모드는 MCP 작업이 Ghidra가 표시하는 동일한 라이브 프로그램 객체에 대해 작동하도록 하려는 경우 사용합니다.
--gui는 --transport streamable-http(또는 별칭으로 --transport http)가 필요합니다.--project-path는 프로젝트 디렉토리와 --project-name을 조합하거나 기존 .gpr 파일일 수 있습니다. 없는 프로젝트는 자동으로 생성됩니다.pyghidra-mcp에 의해 실행되며, 이는 GUI와 MCP 트랜잭션을 동일한 JVM에서 유지합니다.--gui로 실행할 때만 노출됩니다.예:```bash
pyghidra-mcp
--gui
--transport streamable-http
--project-path /absolute/path/to/my_research.gpr
GUI 모드는 다음을 원할 때 적합한 선택입니다:
- CodeBrowser에서 프로그램을 열거나 전환
- 리스팅에서 함수나 주소로 이동
- 함수 이름을 바꾸거나 주석을 추가하고 Ghidra에서 해당 변경 사항을 즉시 확인
### 시작 기본값 및 대규모 프로젝트
`pyghidra-mcp`는 기본적으로 `--wait-for-analysis`를 요구하지 않습니다. 서버는 분석과 MCP 측 인덱싱이 백그라운드에서 계속되는 동안 시작될 수 있습니다.
이는 대규모 프로젝트에서 중요합니다:
- 여러 바이너리가 포함된 프로젝트를 시작해도 서버 시작이 차단될 필요가 없습니다
- 요청을 처리하기 전에 완전히 분석된 프로젝트가 필요하면 `--wait-for-analysis`를 사용할 수 있습니다
- 대규모 기존 프로젝트에서는 분석 및 인덱싱 준비 상태가 바이너리마다 다를 수 있습니다
현재 제한 사항:
- Ghidra 분석 상태와 MCP 인덱싱 상태는 분리되어 있습니다
- `search_strings` 또는 의미 기반 `search_code`가 MCP 측 인덱싱을 기다리는 동안에도 바이너리는 Ghidra에서 완전히 분석될 수 있습니다
- 이는 더 큰 기존 프로젝트를 열 때 더 두드러집니다
실제로는:
- 인덱싱 중심 검색 기능이 따라잡는 동안에도 디컴파일, 탐색, 이름 바꾸기 및 주석은 바이너리에서 계속 작동할 수 있습니다
- 시작 지연 시간이 즉시 검색 준비보다 더 중요하다면 기본값인 `--no-wait-for-analysis`를 유지하십시오
- 시작 시간보다 즉시 준비 상태가 더 중요하다면 `--wait-for-analysis`를 사용하십시오
## 개발
이 프로젝트는 개발과 테스트를 간소화하기 위해 `Makefile`을 사용합니다. `ruff`는 린팅과 포맷팅에 사용되며, `pre-commit` 훅은 코드 품질을 보장하는 데 사용됩니다.
### 설정
1. **`uv` 설치**: `uv`가 설치되어 있지 않다면 pip를 사용하여 설치할 수 있습니다:
```bash
pip install uv
또는 공식 uv 설치 가이드를 참조하세요: https://docs.astral.sh/uv/install/
make dev-setup
source ./.venv/bin/activate
GHIDRA_INSTALL_DIR 환경 변수를 Ghidra 설치 디렉터리로 설정하세요.# For Linux / Mac
export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
# For Windows PowerShell
[System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
Makefile은 테스트 및 코드 품질을 위한 여러 대상을 제공합니다:
make run: MCP 서버를 실행합니다.make test: 전체 테스트 스위트(단위 및 통합)를 실행합니다.make test-unit: 단위 테스트를 실행합니다.make test-integration: 통합 테스트를 실행합니다.make test-integration-fast: pre-commit에서 사용하는 가벼운 통합 스모크 테스트를 실행합니다.make test-integration-gui: GUI 통합 테스트를 실행합니다. 작동하는 Ghidra 설치와 GUI 지원이 필요합니다.make lint: ruff로 코드 스타일을 확인합니다.make format: ruff로 코드를 포맷합니다.make typecheck: ruff로 가벼운 정적 검사를 실행합니다.make check: 모든 품질 검사를 실행합니다.make dev: 개발 워크플로(포맷 및 검사)를 실행합니다.make build: 배포 패키지를 빌드합니다.make clean: 빌드 산출물과 캐시를 정리합니다.권장 분할:
ruff, pyright, 단위 테스트 및 하나의 가벼운 통합 스모크 테스트Xvfb를 사용한 Linux GUI, CLI 커버리지 및 현재 macOS 스모크 테스트LLM이 작업을 수행하고, 결정적 계산을 실행하고, 외부 서비스와 상호 작용할 수 있도록 합니다.
decompile_function 및 list_xrefs는 단일 대상 또는 대상 목록을 허용하므로 호출 체인이나 여러 심볼을 한 번에 분석할 때 왕복 횟수를 줄여줍니다.```jsonc
// Decompile three functions in one call, with callees and xrefs attached
{
"binary_name": "firmware.bin",
"name_or_address": ["main", "init_hardware", "0x08001234"],
"include_callees": true,
"include_xrefs": true
}
// Get cross-references for multiple symbols at once { "binary_name": "firmware.bin", "name_or_address": ["malloc", "free", "realloc"] }
항목별 오류는 인라인으로 반환됩니다(다른 대상은 여전히 성공합니다):```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0): 의미론적 벡터 검색 또는 리터럴 일치를 사용하여 디컴파일된 의사 C 코드를 검색합니다.
list_xrefs(binary_name: str, name_or_address: str | list[str]): 함수(들), 심볼(들) 또는 주소(들)에 대한 교차 참조를 나열합니다. 단일 대상을 허용하거나 배치 조회를 위해 목록을 허용합니다.
gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120): 지정된 함수에 대한 MermaidJS 호출 그래프를 생성합니다. "calling"(대상이 호출하는 함수) 및 "called"(대상을 호출하는 함수) 방향을 모두 지원하며 여러 시각화 유형을 제공합니다.
decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30): 이름이나 주소로 함수(들)를 디컴파일합니다. 단일 대상 또는 배치 디컴파일을 위한 목록을 허용합니다. 풍부한 응답 플래그는 각 결과에 호출된 함수(callees), 문자열 및/또는 교차 참조를 첨부합니다. timeout_sec는 대상별로 적용되며 각 디컴파일 시도를 독립적으로 제한합니다.
list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): 지정된 바이너리에서 내보낸 모든 함수와 심볼을 나열합니다(쿼리에 정규식 지원).
list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): 지정된 바이너리에 대해 가져온 모든 함수와 심볼을 나열합니다(쿼리에 정규식 지원).
read_bytes(binary_name: str, address: str, size: int = 32): 지정된 주소의 메모리에서 원시 바이트를 읽습니다. 16진수 주소에는 0x 접두사가 포함되거나 생략될 수 있습니다.
search_strings(binary_name: str, query: str, limit: int = 100): 바이너리 내에서 문자열을 검색합니다.
search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25): 이름으로 바이너리 내의 심볼을 검색합니다. 대소문자를 구분하지 않는 정규식 패턴(예: ^main$, func.*one) 또는 일반 부분 문자열 쿼리를 지원합니다. functions_only=True로 설정하면 레이블, 변수 및 기타 함수가 아닌 심볼을 제외합니다.
import_binary(binary_path: str): 지정된 경로에서 현재 Ghidra 프로젝트로 바이너리를 가져옵니다. 경로가 디렉터리인 경우 지원되는 모든 바이너리 파일을 재귀적으로 스캔하여 가져오며, Ghidra 프로젝트 내에서 디렉터리 구조를 유지합니다.
list_project_binaries(): 현재 Ghidra 프로젝트의 바이너리를 나열합니다. GUI 모드에서는 CodeBrowser에서 현재 열려 있지 않더라도 디스크에 존재하는 프로젝트 바이너리가 포함됩니다.
list_project_binary_metadata(binary_name: str): 특정 바이너리에 대한 아키텍처, 컴파일러, 실행 파일 형식, 분석 메트릭 및 파일 해시를 포함한 상세 메타데이터를 검색합니다.
delete_project_binary(binary_name: str): Ghidra 프로젝트에서 바이너리(프로그램)를 삭제합니다.
rename_function(binary_name: str, name_or_address: str, new_name: str): 이름이나 주소로 함수의 이름을 바꿉니다. GUI 모드에서는 라이브 Ghidra 트랜잭션으로 실행되어 열린 프로그램을 업데이트합니다.
rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str): 특정 함수 내에서 정확한 이름으로 함수 매개변수 또는 지역 변수의 이름을 바꿉니다. 해당 함수 내에서 이름이 없거나 모호한 경우 도구는 추측 대신 오류를 반환합니다. GUI 모드에서는 라이브 Ghidra 트랜잭션으로 실행되어 열린 프로그램을 업데이트합니다.
set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str): 특정 함수 내에서 정확한 이름으로 함수 매개변수 또는 지역 변수의 데이터 유형을 설정합니다. 해당 함수 내에서 이름이 없거나 모호한 경우 도구는 추측 대신 오류를 반환합니다. type_name은 프로그램 데이터 유형 관리자에 대해 Ghidra의 데이터 유형 파서를 사용하여 구문 분석됩니다.
set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str): 전체 시그니처 문자열에서 함수 프로토타입을 설정합니다. 도구는 항상 Ghidra의 네이티브 시그니처 파서를 통해 프로토타입을 실행하며, 프로토타입이 유효하지 않은 경우 기본 파서 또는 적용 오류를 반환합니다.
set_comment(binary_name: str, target: str, comment: str, comment_type: str): 함수/디컴파일러 주석 또는 리스팅 주석을 설정합니다. 리스팅 주석 대상은 주소, 심볼 또는 함수일 수 있습니다. 지원되는 comment_type 값은 decompiler, plate, pre, eol, post 및 repeatable입니다.
--gui 전용)다음 도구는 pyghidra-mcp가 --gui로 시작될 때만 사용할 수 있으며, 프로젝트 데이터를 직접 변경하는 대신 GUI에 표시되는 내용을 제어합니다:
list_open_programs(): Ghidra GUI에서 현재 열려 있는 프로그램을 나열합니다.open_program_in_gui(binary_name: str, new_window: bool = True): CodeBrowser에서 프로젝트 바이너리를 엽니다. 기본적으로 새 CodeBrowser 창을 엽니다. 가능하면 보이는 CodeBrowser를 재사용하려면 new_window=false로 설정합니다.set_current_program(binary_name: str): 열린 프로그램을 기본 GUI 도구 컨텍스트의 활성/현재 프로그램으로 만듭니다.goto(binary_name: str, target: str, target_type: str): Ghidra GUI를 주소 또는 함수로 이동합니다. target_type은 address 또는 function이어야 합니다.이 Python 패키지는 PyPI에 pyghidra-mcp로 게시되며 pip, pipx, uv, poetry 또는 모든 Python 패키지 관리자로 설치 및 실행할 수 있습니다.```text $ uvx pyghidra-mcp --help Usage: pyghidra-mcp [OPTIONS] [INPUT_PATHS]...
PyGhidra Command-Line MCP server
Options: -v, --version Show version and exit. -t, --transport [stdio|streamable-http|sse|http] Transport protocol. SSE is deprecated; use streamable-http instead. [default: stdio] -p, --port INTEGER Port for HTTP-based transports. [default: 8000] -o, --host TEXT Host for HTTP-based transports. [default: 127.0.0.1] --project-path PATH Directory for a pyghidra-mcp project or an existing Ghidra .gpr file. [default: pyghidra_mcp_projects] --project-name TEXT Ghidra project name. Ignored for .gpr paths. [default: my_project] --threaded / --no-threaded Allow threaded analysis. [default: threaded] --max-workers INTEGER Number of analysis workers; 0 means CPU count. [default: 0] --wait-for-analysis / --no-wait-for-analysis Wait for initial analysis before starting. [default: no-wait-for-analysis] --gui / --no-gui Launch Ghidra GUI in-process and serve MCP against GUI-open programs. Cannot attach to an already-running external Ghidra process. [default: no-gui] --list-project-binaries List ingested project binaries and exit. --delete-project-binary TEXT Delete a project binary by name and exit. --force-analysis / --no-force-analysis Force a new binary analysis each run. [default: no-force-analysis] --verbose-analysis / --no-verbose-analysis Verbose logging for analysis. [default: no-verbose-analysis] --no-symbols / --with-symbols Turn off symbols for analysis. [default: with-symbols] --sym-file-path PATH Single PDB symbol file for one binary. -s, --symbols-path PATH Local symbols directory. --gdt PATH Path to GDT files. May be specified multiple times. --program-options PATH JSON file with Ghidra program options. --gzfs-path PATH Location to store GZFs of analyzed binaries. -h, --help Show this message and exit.
### Docker로 바이너리 매핑하기
Docker 컨테이너를 사용할 때, 바이너리가 포함된 로컬 디렉터리를 컨테이너의 작업 공간에 매핑할 수 있습니다. 이를 통해 `pyghidra-mcp`가 파일을 분석할 수 있습니다.```bash
# Create and populate the new directory
mkdir -p ./binaries
cp /path/to/your/binaries/* ./binaries/
# Run the Docker container with volume mapping
docker run -i --rm \
-v "$(pwd)/binaries:/binaries" \
ghcr.io/clearbluejar/pyghidra-mcp \
/binaries/*
MCPO를 사용하여 pyghidra-mcp를 OpenWeb-UI와 통합할 수 있습니다. MCPO는 MCP-to-OpenAPI 프록시로, pyghidra-mcp의 도구를 표준 RESTful API를 통해 노출하여 웹 인터페이스 및 기타 도구에서 접근할 수 있게 합니다.
uvx 사용 시uvx를 사용하여 pyghidra-mcp와 mcpo를 함께 실행할 수 있습니다:```bash
uvx mcpo --
pyghidra-mcp /bin/ls
#### Docker로
mcpo를 Docker와 함께 사용할 수 있습니다:```bash
uvx mcpo -- docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp /bin/ls
stdio 전송은 표준 입력 및 출력 스트림을 통한 통신을 가능하게 합니다. 이는 로컬 통합 및 명령줄 도구에 특히 유용합니다. 자세한 내용은 명세를 참조하세요.
pyghidra-mcp
기본적으로 Python 패키지는 `stdio` 모드로 실행됩니다. 표준 입력 및 출력 스트림을 사용하기 때문에 도구가 출력 없이 멈춘 것처럼 보일 수 있지만, 이는 정상입니다.
#### Docker
이 서버는 GitHub Container Registry([ghcr.io/clearbluejar/pyghidra-mcp](http://ghcr.io/clearbluejar/pyghidra-mcp))에 게시되어 있습니다.```
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio
기본적으로 Docker 컨테이너는 streamable-http 서버를 시작하므로, 이미지 이름 뒤에 -t stdio를 포함하고 대화형 stdio 모드로 실행하려면 -i를 사용하세요.
Streamable HTTP는 HTTP POST 요청을 통해 JSON RPC에서 스트리밍 응답을 지원합니다. 자세한 내용은 사양을 참조하세요.
기본적으로 서버는 클라이언트 연결을 위해 http://127.0.0.1:8000/mcp에서 수신 대기합니다. 바인드 주소를 변경하려면 --host / --port 또는 MCP_HOST / MCP_PORT 환경 변수를 사용하세요. 클라이언트가 연결하려면 서버가 실행 중이어야 합니다.
pyghidra-mcp -t streamable-http
기본적으로 Python 패키지는 `stdio` 모드로 실행되므로 `-t streamable-http`를 포함해야 합니다.
GUI 모드는 이 전송 방식을 사용합니다:```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_project.gpr
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
### 서버 전송 이벤트 (SSE)
> [!WARNING]
> MCP 커뮤니티에서는 이 프로토콜을 이전 버전과의 호환성을 위한 레거시 전송 프로토콜로 간주합니다. [Streamable HTTP](#streamable-http)가 권장되는 대체 수단입니다.
SSE 전송은 서버-클라이언트 간 스트리밍을 위해 Server-Send Events를 사용하여 클라이언트-서버 및 서버-클라이언트 통신을 지원합니다. 자세한 내용은 [사양](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse)을 참조하세요.
기본적으로 서버는 클라이언트 연결을 위해 [http://127.0.0.1:8000/sse](http://127.0.0.1:8000/sse)에서 수신 대기합니다. `--host` / `--port` 또는 `MCP_HOST` / `MCP_PORT` 환경 변수를 사용하여 바인드 주소를 변경할 수 있습니다. _클라이언트가 연결하려면 서버가 실행 중이어야 합니다._
#### Python```bash
pyghidra-mcp -t sse
기본적으로 Python 패키지는 stdio 모드로 실행되므로 -t sse를 포함해야 합니다.
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse
## 통합
> [!NOTE]
> 이 섹션은 작업 진행 중입니다. 곧 특정 통합에 대한 예제를 추가할 예정입니다.
### Claude Desktop
`claude_desktop_config.json` 파일에 다음 JSON 블록을 추가하세요:```json
{
"mcpServers": {
"pyghidra-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/clearbluejar/pyghidra-mcp",
"pyghidra-mcp",
"--project-path",
"/tmp/pyghidra", // or path to writeable directory
"/bin/ls" //
],
"env": {
"GHIDRA_INSTALL_DIR": "/path/to/ghidra/ghidra_12.0_PUBLIC"
}
}
}
}
이 프로젝트의 구현과 설계는 다음과 같은 멋진 프로젝트에서 영감을 받았습니다:
우리는 리버스 엔지니어링의 미래가 에이전트 기반이고, 상황에 맞으며, 확장 가능할 것이라고 믿습니다.
pyghidra-mcp는 전체 Ghidra 프로젝트를 AI 에이전트와 자동화 파이프라인에서 사용할 수 있게 만드는, 그 미래를 향한 한 걸음입니다.
우리는 프로젝트를 활발히 개발 중이며 피드백, 이슈, 기여를 환영합니다.
[!NOTE] 우리는 여러분의 피드백, 버그 리포트, 기능 요청, 코드를 환영합니다.
새로운 도구나 통합을 추가하는 경우 권장 워크플로우는 다음과 같습니다:
feature/ 접두사를 붙이세요.pyghidra/tools/에 있는 기존 도구와 동일한 스타일과 구조로 도구를 추가하세요.StdioClient 인스턴스를 사용하여 도구를 실행하는 통합 테스트를 작성하세요. tests/integration/에 배치하세요.tests/integration/test_concurrent_streamable_client.py에 도구 호출을 추가하여 동시성 테스트를 확장하세요.이렇게 하면 코드베이스 전반의 일관성이 유지되고 리버스 엔지니어링 워크플로우를 위한 강력하고 확장 가능한 도구를 유지하는 데 도움이 됩니다.
❤️를 담아 PyGhidra-MCP 팀이 제작했습니다.