Python 명령줄 Ghidra MCP
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/41597/82f9c5eb55db6134d47587275fce66c4ed32b86b5332f7e2d610fa0214070a7f.png" width=60% >
</p>
<p align="center">
<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
</p>
# PyGhidra-MCP - Ghidra Model Context Protocol 서버
### 개요
**`pyghidra-mcp`**는 강력한 소프트웨어 리버스 엔지니어링(SRE) 제품군인 [Ghidra](https://ghidra-sre.org/)의 모든 분석 기능을 지능형 에이전트와 LLM 기반 도구의 세계로 가져오는 명령줄 Model Context Protocol(MCP) 서버입니다.
Ghidra의 [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html)와 [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html)를 `pyghidra`와 `jpype`를 사용하여 Python으로 연결한 다음, 그 기능을 Model Context Protocol을 통해 노출합니다.
MCP는 언어 모델, 개발 도구(예: VS Code), 자율 에이전트가 구조화된 컨텍스트에 접근하고, 도구를 호출하며, 지능적으로 협업할 수 있게 해주는 통합 인터페이스입니다. MCP를 강력한 분석 도구와 LLM 생태계 사이의 다리라고 생각하면 됩니다.
`pyghidra-mcp`를 사용하면 Ghidra는 지능형 백엔드가 됩니다. 컨텍스트가 풍부한 쿼리에 응답하고, 심층 리버스 엔지니어링 작업을 자동화하며, AI 지원 워크플로에 통합될 준비가 된 백엔드입니다.
`pyghidra-mcp`는 이제 두 가지 운영 모드를 지원합니다:
- CLI 기반 분석 및 자동화를 위한 `headless` 모드
- `pyghidra-mcp`를 통해 Ghidra를 실행하고 실행 중인 GUI와 라이브 프로그램 상태를 공유하는 `--gui` 모드
> [!NOTE]
> 이 베타 프로젝트는 활발히 개발 중입니다. 여러분의 피드백, 버그 리포트, 기능 요청, 코드를 기다리고 있습니다.
## 또 다른 Ghidra MCP?
네, 원래의 [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP)는 훌륭합니다. 하지만 `pyghidra-mcp`는 다른 접근 방식을 취합니다:
- 🐍 **헤드리스 우선, GUI 지원** – 간소화된 자동화를 위해 전적으로 CLI로 실행하거나, 라이브 GUI 탐색 및 편집을 원할 때 `--gui`로 Ghidra를 실행할 수 있습니다.
- 🔁 **자동화를 위해 설계됨** – LLM, CI 파이프라인, 반복 가능한 동작이 필요한 도구와의 통합에 이상적입니다.
- ✅ **CI/CD 친화적** – 클라이언트와 서버 세션 모두를 위한 견고한 단위 및 통합 테스트로 구축되었습니다.
- 🚀 **빠른 시작** – 비동기 시작을 통해 바이너리가 백그라운드에서 분석되는 동안에도 서버가 요청 처리를 시작할 수 있습니다. 최소한의 설정으로 빠른 명령줄 실행을 지원합니다.
- 📦 **프로젝트 전체 분석** – Ghidra 프로젝트의 모든 바이너리에 대한 동시 리버스 엔지니어링을 가능하게 합니다
- 🤖 **에이전트 준비 완료** – 지능형 에이전트 기반 워크플로와 대규모 리버스 엔지니어링 자동화를 위해 구축되었습니다.
- 🔍 시맨틱 코드 검색 – 벡터 임베딩(ChromaDB 사용)을 통해 디컴파일된 함수, 주석, 심볼 전반에 걸친 빠르고 유연한 조회를 가능하게 합니다. 의사 C 탐색과 에이전트 기반 트리아지에 완벽합니다.
이 프로젝트는 로컬 개발, 헤드리스 환경, 테스트 가능한 워크플로에 최적화된 Python 우선 경험을 제공합니다.
## 설정 다이어그램
### 구성 요소들이 연결되는 방식
```mermaid
flowchart LR
subgraph Clients["Clients"]
Agent["MCP host / agent"]
Cli["pyghidra-mcp-cli"]
User["Ghidra user"]
end
subgraph Process["pyghidra-mcp process"]
Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
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 -->|"HTTP (recommended)"| 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"]
Start --> GuiNeed["Live Ghidra GUI control"]
Start --> Terminal["Interactive terminal client"]
Headless --> Http["pyghidra-mcp<br/>--transport 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"]
```
- **헤드리스 MCP**: `streamable-http`를 사용하세요. Ghidra와 그 프로젝트를 하나의 장기 실행 서버로 유지하며, MCP 호스트와 CLI 클라이언트 모두에서 작동합니다.
- **GUI 모드**: `pyghidra-mcp`는 Ghidra를 실행하고, 프로젝트를 열며, 동일한 JVM에서 CodeBrowser를 제어하는 추가 도구를 노출합니다.
- **CLI 클라이언트**: `pyghidra-mcp-cli`는 HTTP 클라이언트입니다. 먼저 `streamable-http` 서버를 시작한 다음, 실행 중인 서버에 대해 터미널 명령을 실행하세요.
- **stdio**: HTTP 엔드포인트에 연결할 수 없는 MCP 호스트에만 이 옵션을 유지하세요.
<details>
<summary>자세한 아키텍처 및 도구 표면</summary>
```mermaid
flowchart TD
subgraph Clients
Agent["LLM / MCP host"]
Cli["pyghidra-mcp-cli"]
Automation["scripts and CI"]
end
subgraph Transports
Stdio["stdio"]
Http["streamable-http"]
Sse["sse legacy"]
end
subgraph Server["pyghidra-mcp server"]
McpServer["MCPServer 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 --> Http
Automation --> Http
Automation --> Sse
Cli --> Http
Stdio --> McpServer
Http --> McpServer
Sse --> McpServer
McpServer --> Context
Context --> PyGhidra
PyGhidra --> Jpype
Jpype --> Project
Project --> Programs
Context --> Indexing
Indexing --> Search
McpServer --> 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)
- [스트리머블 HTTP](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [표준 입출력(stdio)](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [OpenWeb-UI 및 MCPO와 함께 사용하기](#using-with-openweb-ui-and-mcpo)
- [`uvx` 사용](#with-uvx)
- [Docker 사용](#docker-2)
- [서버 전송 이벤트(SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [영감](#inspiration)
- [기여, 커뮤니티 및 소스에서 실행하기](#contributing-community-and-running-from-source)
- [기여자 워크플로](#contributor-workflow)
## 시작하기
[Python 패키지](https://pypi.org/p/pyghidra-mcp)와 [`uv`](https://docs.astral.sh/uv/guides/tools/)를 사용하여 지속적인 스트리머블 HTTP 서버를 시작하세요:
```bash
uvx pyghidra-mcp \
--transport streamable-http \
--project-path /absolute/path/to/ghidra-projects \
/absolute/path/to/binary
```
서버는 그러면 `http://127.0.0.1:8000/mcp`에서 사용할 수 있습니다. 실행 상태로 두고 MCP 클라이언트가 해당 URL을 사용하도록 구성하세요. 아래의 [Claude Code](#claude-code) 및 [Codex](#codex) 예시는 예상되는 구성을 보여줍니다.
MCP에서 실행 중인 Ghidra GUI를 시작하고 제어하려면 `streamable-http`와 함께 `--gui`를 사용하세요:
```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 --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## 에이전트에 최적화됨
`pyghidra-mcp`는 MCP 표면을 의도적으로 좁게 유지하여 에이전트 클라이언트가 도구 검색과 인수 선택에 더 적은 토큰을 소비하도록 합니다.
- **간결한 도구 설명**: MCP 도구 docstring은 간결하게 유지되어 MCPServer 도구 스키마가 작고 모델에 전송하기 저렴하게 유지됩니다.
- **컨텍스트 규율**: 도구는 기본적으로 전체 프로그램 컨텍스트를 덤프하는 대신 집중된 구조화 데이터를 반환합니다. 디컴파일, 심볼 검색, 교차 참조 결과는 하나의 큰 응답이 아닌 반복적 분석을 지원하도록 구성됩니다.
- **관련 있을 때만 GUI 도구**: `open_program_in_gui`, `list_open_programs`, `set_current_program`, `goto`와 같은 GUI 전용 컨트롤은 서버가 `--gui`로 시작된 경우에만 노출됩니다.
- **CLI는 선택 사항**: MCP가 선호하는 인터페이스가 아니라면, `pyghidra-mcp-cli`는 일반적인 편집 및 분석 워크플로를 위한 그룹화된 명령을 갖춘 HTTP 기반의 직접 명령줄 클라이언트를 제공합니다.
이를 통해 기본 서버는 불필요한 도구 표면이나 헤드리스 세션에서 GUI 전용 컨트롤을 노출하지 않고도 LLM 에이전트, IDE 통합, 자동화에 사용할 수 있게 유지됩니다.
## CLI 클라이언트
보다 대화형 명령줄 환경을 원한다면, 실행 중인 pyghidra-mcp 서버와 상호 작용하기 위한 사용자 친화적 인터페이스를 제공하는 별도의 **pyghidra-mcp-cli** 패키지를 사용할 수 있습니다.
### 설치
[`uv`](https://docs.astral.sh/uv/)를 사용하여 CLI 클라이언트를 설치합니다(권장):
```bash
uvx pyghidra-mcp-cli
```
pip로 설치하거나:
```bash
pip install pyghidra-mcp-cli
```
### CLI로 빠르게 시작하기
1. **서버 시작** (한 터미널에서):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
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](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md)를 참조하세요.
## 프로젝트 생성, 관리 및 기존 프로젝트 열기
### 새 프로젝트 생성
워크플로우에 따라 여러 가지 방법으로 새 프로젝트를 생성할 수 있습니다:
#### 자체 포함 프로젝트 구조
`pyghidra-mcp`는 각 프로젝트가 자체 Ghidra 프로젝트와 pyghidra-mcp 아티팩트를 갖는 **자체 포함 프로젝트 구조**를 생성합니다. 이를 통해 완전한 격리와 손쉬운 프로젝트 관리가 보장됩니다.
#### 기본 프로젝트 생성
```bash
# Create a new project with default settings
pyghidra-mcp
# Creates:
$ 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
```
#### 여러 관련 프로젝트 생성하기
```bash
# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace
# Project for suspicious binaries
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
# Project for packed malware
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 모드
Ghidra가 표시하는 것과 동일한 라이브 프로그램 객체에 대해 MCP 작업을 수행하려면 GUI 모드를 사용하십시오.
- `--gui`는 `--transport streamable-http`(또는 별칭인 `--transport http`)를 필요로 합니다
- `--project-path`는 프로젝트 디렉터리와 `--project-name`의 조합이거나 기존 `.gpr` 파일일 수 있습니다. 누락된 프로젝트는 자동으로 생성됩니다.
- Ghidra는 `pyghidra-mcp`에 의해 실행되며, GUI와 MCP 트랜잭션을 동일한 JVM에서 유지합니다
- GUI 전용 도구는 `--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 인덱싱 상태는 별개입니다
- 바이너리가 Ghidra에서 완전히 분석되었더라도 `search_strings` 또는 시맨틱 `search_code`가 여전히 MCP 측 인덱싱을 기다리고 있을 수 있습니다
- 이는 더 큰 기존 프로젝트를 열 때 더 두드러집니다
실제로:
- 디컴파일, 탐색, 이름 변경, 주석은 인덱싱이 많은 검색 기능이 따라잡는 동안에도 바이너리에 대해 여전히 작동할 수 있습니다
- 시작 지연이 즉각적인 검색 준비보다 더 중요하다면 기본 `--no-wait-for-analysis`를 유지하세요
- 즉각적인 준비가 시작 시간보다 더 중요하다면 `--wait-for-analysis`를 사용하세요
## Development
이 프로젝트는 개발과 테스트를 간소화하기 위해 `Makefile`을 사용합니다. `ruff`는 린팅과 포매팅에 사용되며, `pre-commit` 훅은 코드 품질을 보장하는 데 사용됩니다.
### Setup
1. **`uv` 설치**: `uv`가 설치되어 있지 않다면 pip를 사용하여 설치할 수 있습니다:
```bash
pip install uv
```
또는 공식 `uv` 설치 가이드를 따르세요: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **가상 환경 생성 및 의존성 설치**:
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **Ghidra 환경 변수 설정**: Ghidra를 다운로드하고 설치한 다음, `GHIDRA_INSTALL_DIR` 환경 변수를 Ghidra 설치 디렉터리로 설정하세요.
```bash
# For Linux / Mac
export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
# For Windows PowerShell
[System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/main/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
```
### Testing and Quality
`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`: 빌드 아티팩트와 캐시를 정리합니다.
권장 분할:
- pre-commit: `ruff`, `pyright`, 단위 테스트, 그리고 하나의 경량 통합 스모크 테스트
- GitHub Actions: 전체 Linux 헤드리스 통합 커버리지, `Xvfb` 하의 Linux GUI, CLI 커버리지, 그리고 현재 macOS 스모크 테스트
- 예약된 CI: 구버전 macOS / Ghidra 호환성 커버리지
- 로컬/수동: 더 무거운 환경별 GUI 디버깅 및 릴리스 정상 작동 확인
## API
### Tools
LLM이 작업을 수행하고, 결정론적 계산을 하고, 외부 서비스와 상호작용할 수 있게 합니다.
#### Batch Operations
`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)`: 이름 또는 주소로 함수를 디컴파일합니다. 단일 대상 또는 일괄 디컴파일을 위한 목록을 허용합니다. 풍부한 응답 플래그는 각 결과에 피호출자, 문자열 및/또는 교차 참조를 첨부합니다. `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 제어 도구 (`--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 패키지는 [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp)로 PyPI에 게시되어 있으며, [pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package), [pipx](https://pipx.pypa.io/), [uv](https://docs.astral.sh/uv/), [poetry](https://python-poetry.org/) 또는 모든 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/*
```
### Streamable HTTP
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)