Ghidra MCP для командной строки на Python
<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 - сервер Model Context Protocol для Ghidra
### Обзор
**`pyghidra-mcp`** — это сервер Model Context Protocol (MCP) с интерфейсом командной строки, который привносит всю аналитическую мощь [Ghidra](https://ghidra-sre.org/), надёжного набора для обратной разработки программного обеспечения (SRE), в мир интеллектуальных агентов и инструментов на основе LLM.
Он связывает [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) Ghidra с Python через `pyghidra` и `jpype`, а затем предоставляет эту функциональность через Model Context Protocol.
MCP — это унифицированный интерфейс, позволяющий языковым моделям, инструментам разработки (таким как VS Code) и автономным агентам получать доступ к структурированному контексту, вызывать инструменты и интеллектуально взаимодействовать. Воспринимайте MCP как мост между мощными инструментами анализа и экосистемой LLM.
С `pyghidra-mcp` Ghidra становится интеллектуальным бэкендом — готовым отвечать на контекстно-насыщенные запросы, автоматизировать глубокие задачи обратной разработки и интегрироваться в рабочие процессы с поддержкой ИИ.
`pyghidra-mcp` теперь поддерживает два режима работы:
- режим `headless` для анализа и автоматизации через CLI
- режим `--gui`, который запускает Ghidra через `pyghidra-mcp` и делится текущим состоянием программы с работающим GUI
> [!NOTE]
> Этот бета-проект находится в активной разработке. Мы будем рады вашим отзывам, сообщениям об ошибках, запросам на новые функции и коду.
## Ещё один Ghidra MCP?
Да, оригинальный [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) великолепен. Но `pyghidra-mcp` использует другой подход:
- 🐍 **Headless-first, с поддержкой GUI** – Полностью работает через CLI для оптимизированной автоматизации или запускает Ghidra с `--gui`, когда нужна живая навигация и правки в GUI.
- 🔁 **Создан для автоматизации** – Идеален для интеграции с LLM, CI-конвейерами и инструментами, требующими воспроизводимого поведения.
- ✅ **Дружелюбен к CI/CD** – Построен с надёжными модульными и интеграционными тестами как для клиентских, так и для серверных сессий.
- 🚀 **Быстрый запуск** – Асинхронный запуск позволяет серверу начинать обработку запросов, пока бинарные файлы всё ещё анализируются в фоне. Поддерживает быстрый запуск из командной строки с минимальной настройкой.
- 📦 **Анализ в масштабе проекта** – Обеспечивает параллельную обратную разработку всех бинарных файлов в проекте Ghidra
- 🤖 **Готов к работе с агентами** – Создан для рабочих процессов на основе интеллектуальных агентов и крупномасштабной автоматизации обратной разработки.
- 🔍 Семантический поиск по коду – Использует векторные эмбеддинги (через ChromaDB) для быстрого нечёткого поиска по декомпилированным функциям, комментариям и символам — идеально для исследования псевдокода и сортировки задач агентами.
Этот проект предлагает опыт, ориентированный в первую очередь на Python, оптимизированный для локальной разработки, headless-сред и тестируемых рабочих процессов.
## Схемы настройки
### Как всё связано
```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"]
```
- **Headless MCP**: используйте `streamable-http`. Он сохраняет Ghidra и её проект как один долго работающий сервер и работает как с MCP-хостами, так и с CLI-клиентом.
- **Режим GUI**: `pyghidra-mcp` запускает Ghidra, открывает проект и предоставляет дополнительные инструменты, управляющие CodeBrowser в той же JVM.
- **CLI-клиент**: `pyghidra-mcp-cli` — это HTTP-клиент. Сначала запустите сервер `streamable-http`, затем отправляйте терминальные команды этому работающему серверу.
- **stdio**: сохраняйте этот режим только для MCP-хостов, которые не могут подключиться к HTTP-эндпоинту.
<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 — сервер Model Context Protocol для 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)
- [Streamable 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)
- [Server-sent events (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Вдохновение](#inspiration)
- [Участие в разработке, сообщество и запуск из исходного кода](#contributing-community-and-running-from-source)
- [Рабочий процесс участника](#contributor-workflow)
## Начало работы
Запустите постоянный сервер Streamable HTTP, используя [пакет Python](https://pypi.org/p/pyghidra-mcp) и [`uv`](https://docs.astral.sh/uv/guides/tools/):
```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) ниже показывают ожидаемую конфигурацию.
Чтобы запустить и управлять работающим GUI Ghidra из MCP, используйте `--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` запускает Ghidra через `pyghidra-mcp`. Он не подключается к уже запущенному внешнему экземпляру Ghidra.
Или запустите как [Docker-контейнер](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Оптимизировано для агентов
`pyghidra-mcp` намеренно сохраняет поверхность MCP узкой, чтобы клиенты-агенты тратили меньше токенов на обнаружение инструментов и выбор аргументов.
- **Краткие описания инструментов**: docstring'и инструментов MCP остаются компактными, чтобы схемы инструментов MCPServer были небольшими и дешёвыми для отправки моделям.
- **Дисциплина контекста**: инструменты возвращают сфокусированные структурированные данные вместо выгрузки контекста всей программы по умолчанию. Результаты декомпиляции, поиска символов и перекрёстных ссылок формируются так, чтобы поддерживать итеративный анализ, а не один большой ответ.
- **GUI-инструменты только когда это уместно**: элементы управления, доступные только в GUI, такие как `open_program_in_gui`, `list_open_programs`, `set_current_program` и `goto`, предоставляются только при запуске сервера с `--gui`.
- **CLI опционален**: если MCP не является вашим предпочтительным интерфейсом, `pyghidra-mcp-cli` предоставляет прямой клиент командной строки поверх HTTP со сгруппированными командами для типовых рабочих процессов редактирования и анализа.
Это сохраняет сервер по умолчанию пригодным для использования LLM-агентами, интеграциями с IDE и автоматизацией без раскрытия ненужной поверхности инструментов или элементов управления, доступных только в GUI, в headless-сессиях.
## CLI-клиент
Для более интерактивного опыта работы в командной строке вы можете использовать отдельный пакет **pyghidra-mcp-cli**, который предоставляет удобный интерфейс для взаимодействия с запущенным сервером pyghidra-mcp.
### Установка
Установите CLI-клиент с помощью [`uv`](https://docs.astral.sh/uv/) (рекомендуется):
```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 подключается к pyghidra-mcp через HTTP, чтобы избежать накладных расходов на запуск в 10-60 секунд при порождении нового процесса Ghidra для каждой команды. Полную документацию см. в [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
Используйте режим GUI, когда требуется, чтобы действия MCP выполнялись над теми же живыми объектами программы, которые отображает Ghidra.
- `--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`
## Разработка
Этот проект использует `Makefile` для упрощения разработки и тестирования. `ruff` используется для линтинга и форматирования, а хуки `pre-commit` используются для обеспечения качества кода.
### Настройка
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)
```
### Тестирование и качество
`Makefile` предоставляет несколько целей для тестирования и обеспечения качества кода:
- `make run`: Запустить сервер MCP.
- `make test`: Запустить полный набор тестов (модульные и интеграционные).
- `make test-unit`: Запустить модульные тесты.
- `make test-integration`: Запустить интеграционные тесты.
- `make test-integration-fast`: Запустить облегчённый интеграционный smoke-тест, используемый 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`, модульные тесты и один облегчённый интеграционный smoke-тест
- GitHub Actions: полное покрытие интеграционных тестов Linux в headless-режиме, GUI Linux под `Xvfb`, покрытие CLI и текущие smoke-тесты macOS
- запланированный CI: покрытие совместимости со старыми версиями macOS / Ghidra
- локально/вручную: более тяжёлая отладка GUI, зависящая от окружения, и проверки перед релизом
## API
### Инструменты
Позволяют 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)`: Декомпилирует функцию(и) по имени или адресу. Принимает одну цель или список для пакетной декомпиляции. Флаги расширенного ответа прикрепляют вызываемые функции, строки и/или перекрёстные ссылки к каждому результату. `timeout_sec` применяется к каждой цели и независимо ограничивает каждую попытку декомпиляции.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Выводит список всех экспортируемых функций и символов из указанного бинарного файла (поддерживается regex для запроса).
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)