PyGhidra-MCP — сервер Ghidra Model Context Protocol

Обзор

pyghidra-mcp — это сервер Model Context Protocol (MCP) с интерфейсом командной строки, который предоставляет всю аналитическую мощь Ghidra — полнофункционального набора для обратной разработки (software reverse engineering, SRE) — интеллектуальным агентам и инструментам на основе LLM. Он связывает ProgramAPI и FlatProgramAPI Ghidra с Python через pyghidra и jpype, а затем предоставляет эту функциональность через Model Context Protocol.

MCP — это единый интерфейс, который позволяет языковым моделям, инструментам разработки (например, VS Code) и автономным агентам получать структурированный контекст, вызывать инструменты и интеллектуально взаимодействовать. Представьте MCP как мост между мощными инструментами анализа и экосистемой LLM.

С pyghidra-mcp Ghidra превращается в интеллектуальный бэкенд — готовый отвечать на насыщенные контекстом запросы, автоматизировать сложные задачи обратной разработки и интегрироваться в рабочие процессы с поддержкой ИИ.

pyghidra-mcp теперь поддерживает два режима работы:

режим headless для анализа и автоматизации через CLI
режим --gui, который запускает Ghidra через pyghidra-mcp и передаёт текущее состояние программы в работающий графический интерфейс

[!NOTE] Этот бета-проект находится в активной разработке. Мы будем рады вашим отзывам, сообщениям об ошибках, запросам функций и коду.

Ещё один Ghidra MCP?

Да, оригинальный ghidra-mcp замечателен. Но pyghidra-mcp выбирает другой подход:

🐍 Сначала headless, с поддержкой GUI — запускайте полностью через CLI для отлаженной автоматизации либо запускайте Ghidra с --gui, когда нужна живая навигация и редактирование в GUI.
🔁 Создан для автоматизации — идеально подходит для интеграции с LLM, CI-конвейерами и инструментами, которым нужно воспроизводимое поведение.
✅ Дружелюбен к CI/CD — включает надёжные модульные и интеграционные тесты для клиентских и серверных сессий.
🚀 Быстрый запуск — асинхронный старт позволяет серверу начать обрабатывать запросы, пока бинарные файлы ещё анализируются в фоновом режиме. Поддерживает быстрый запуск из командной строки с минимальной настройкой.
📦 Анализ всего проекта — позволяет выполнять параллельную обратную разработку всех бинарных файлов в проекте Ghidra
🤖 Готовность для агентов — создан для рабочих процессов, управляемых интеллектуальными агентами, и автоматизации обратной разработки в больших масштабах.
🔍 Семантический поиск по коду — использует векторные эмбеддинги (через ChromaDB) для быстрого нечёткого поиска по декомпилированным функциям, комментариям и символам — идеально для изучения псевдокода на C и агентной сортировки находок.

Этот проект предлагает подход «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["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"]

Безголовый MCP: используйте stdio для локальных MCP-хостов или streamable-http, когда нескольким клиентам нужен один долго работающий проект Ghidra.
Режим GUI: pyghidra-mcp запускает Ghidra, открывает проект и предоставляет дополнительные инструменты, управляющие CodeBrowser в той же JVM.
CLI-клиент: pyghidra-mcp-cli — это HTTP-клиент. Сначала запустите сервер streamable-http, затем направляйте команды терминала на этот работающий сервер.

Подробная архитектура и набор инструментов

```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"]
    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 Model Context Protocol Server](#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)
    - [Потоковый HTTP](#streamable-http)
      - [Python](#python-1)
      - [Docker](#docker-1)
    - [Server-sent events (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-пакет](https://pypi.org/p/pyghidra-mcp) как CLI-команду с помощью [`uv`](https://docs.astral.sh/uv/guides/tools/):```bash
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default

Графический режим — правильный выбор, когда нужно: - открывать или переключать программы в 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/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`: очистка артефактов сборки и кэша. Рекомендуемое разделение: - pre-commit: `ruff`, `pyright`, модульные тесты и один облегчённый интеграционный смоук-тест - GitHub Actions: полное покрытие headless-интеграции на Linux, Linux GUI под `Xvfb`, покрытие CLI и текущие смоук-тесты 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"] }

#### Инструменты чтения и анализа - `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), строки и/или перекрёстные ссылки (xrefs). `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)`: Читает сырые байты из памяти по указанному адресу. Шестнадцатеричные адреса могут содержать или не содержать префикс `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()`: Выводит список программ, открытых в настоящий момент в GUI Ghidra. - `open_program_in_gui(binary_name: str, new_window: bool = True)`: Открывает бинарный файл проекта в CodeBrowser. По умолчанию открывается новое окно CodeBrowser. Установите `new_window=false`, чтобы по возможности повторно использовать видимое окно CodeBrowser. - `set_current_program(binary_name: str)`: Делает открытую программу активной/текущей программой в основном контексте инструмента GUI. - `goto(binary_name: str, target: str, target_type: str)`: Перемещает GUI Ghidra к адресу или функции. `target_type` должен быть `address` или `function`. ## Использование Этот пакет Python опубликован на PyPI как [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) и может быть установлен и запущен с помощью [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.

## Вдохновение Реализация и дизайн этого проекта вдохновлены этими замечательными проектами: * [GhidraMCP](https://github.com/lauriewired/GhidraMCP) * [semgrep-mcp](https://github.com/semgrep/mcp) * [ghidrecomp](https://github.com/clearbluejar/ghidrecomp) * [BinAssistMCP](https://github.com/jtang613/BinAssistMCP) --- ## Участие, сообщество и запуск из исходного кода Мы верим, что будущее реверс-инжиниринга — за агентными, контекстными и масштабируемыми решениями. `pyghidra-mcp` — это шаг к такому будущему: он делает полные проекты Ghidra доступными для AI-агентов и конвейеров автоматизации. Мы активно развиваем проект и приветствуем обратную связь, сообщения об ошибках и вклад. > [!NOTE] > Нам очень важны ваши отзывы, отчёты об ошибках, запросы новых функций и код. ### Порядок работы контрибьютора Если вы добавляете новый инструмент или интеграцию, рекомендуем следующий порядок работы: - Называйте свою ветку с префиксом `feature/`, чтобы обозначить новую возможность. - Добавляйте свой инструмент в том же стиле и структуре, что и существующие инструменты в `pyghidra/tools/`. - Напишите интеграционный тест, который проверяет ваш инструмент с помощью экземпляра `StdioClient`. Разместите его в `tests/integration/`. - Расширьте параллельное тестирование, добавив вызов вашего инструмента в `tests/integration/test_concurrent_streamable_client.py`. - Запустите make test и make format, чтобы убедиться, что ваши изменения проходят все тесты и соответствуют правилам линтинга. Это обеспечивает согласованность кодовой базы и помогает нам поддерживать надёжные и масштабируемые инструменты для рабочих процессов реверс-инжиниринга. ______________________________________________________________________ Сделано с ❤️ командой [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)

Популярное

pyghidra-mcp

Оптимизировано для агентов

CLI-клиент

Установка

Быстрый старт с CLI

Создание проектов, управление ими и открытие существующих проектов

Создание новых проектов

Автономная структура проекта

Базовое создание проекта```bash

Create a new project with default settings

Creates:

Создание нескольких связанных проектов```bash

Create separate projects for different analysis focuses

Project for suspicious binaries

Project for packed malware

Режим GUI

Сопоставление бинарных файлов с Docker

Create and populate the new directory

Run the Docker container with volume mapping

С помощью Docker

Docker

Server-sent events (SSE)

Python```bash

Интеграции

Claude Desktop