Ghidra-MCP für die Python-Kommandozeile
<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 Server
### Überblick
**`pyghidra-mcp`** ist ein kommandozeilenbasierter Model Context Protocol (MCP)-Server, der die volle Analyseleistung von [Ghidra](https://ghidra-sre.org/), einer robusten Software-Reverse-Engineering-(SRE)-Suite, in die Welt intelligenter Agenten und LLM-basierter Tooling-Umgebungen bringt.
Er verbindet Gidras [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) und [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) über `pyghidra` und `jpype` mit Python und stellt diese Funktionalität anschließend über das Model Context Protocol bereit.
MCP ist eine einheitliche Schnittstelle, die es Sprachmodellen, Entwicklungswerkzeugen (wie VS Code) und autonomen Agenten ermöglicht, auf strukturierten Kontext zuzugreifen, Tooling aufzurufen und intelligent zusammenzuarbeiten. Man kann sich MCP als die Brücke zwischen leistungsstarken Analysewerkzeugen und dem LLM-Ökosystem vorstellen.
Mit `pyghidra-mcp` wird Ghidra zu einem intelligenten Backend – bereit, kontextreiche Abfragen zu beantworten, tiefgehende Reverse-Engineering-Aufgaben zu automatisieren und in KI-gestützte Workflows integriert zu werden.
`pyghidra-mcp` unterstützt jetzt zwei Betriebsmodi:
- `headless`-Modus für CLI-gesteuerte Analyse und Automatisierung
- `--gui`-Modus, der Ghidra über `pyghidra-mcp` startet und den Live-Programmzustand mit der laufenden GUI teilt
> [!NOTE]
> Dieses Beta-Projekt befindet sich in aktiver Entwicklung. Wir freuen uns über Feedback, Fehlerberichte, Feature-Anfragen und Code.
## Noch ein Ghidra MCP?
Ja, das ursprüngliche [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) ist fantastisch. Aber `pyghidra-mcp` verfolgt einen anderen Ansatz:
- 🐍 **Headless-first, GUI-fähig** – Läuft vollständig über die CLI für optimierte Automatisierung oder startet Ghidra mit `--gui`, wenn Sie Live-GUI-Navigation und -Bearbeitung wünschen.
- 🔁 **Für Automatisierung konzipiert** – Ideal für die Integration mit LLMs, CI-Pipelines und Tooling, das reproduzierbares Verhalten erfordert.
- ✅ **CI/CD-freundlich** – Entwickelt mit robusten Unit- und Integrationstests für Client- und Server-Sitzungen.
- 🚀 **Schneller Start** – Asynchroner Start ermöglicht es dem Server, Anfragen zu bearbeiten, während Binärdateien noch im Hintergrund analysiert werden. Unterstützt schnellen Kommandozeilenstart mit minimalem Setup.
- 📦 **Projektweite Analyse** – Ermöglicht gleichzeitiges Reverse Engineering aller Binärdateien in einem Ghidra-Projekt
- 🤖 **Agentenbereit** – Entwickelt für intelligente agentengesteuerte Workflows und groß angelegte Reverse-Engineering-Automatisierung.
- 🔍 Semantische Codesuche – Verwendet Vektor-Embeddings (über ChromaDB), um schnelle, unscharfe Suche über dekompilierte Funktionen, Kommentare und Symbole zu ermöglichen – perfekt für Pseudo-C-Erkundung und agentengesteuerte Triage.
Dieses Projekt bietet eine Python-first-Erfahrung, optimiert für lokale Entwicklung, Headless-Umgebungen und testbare Workflows.
## Setup-Diagramme
### Wie die Komponenten zusammenspielen
```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
```
### Auswahl eines Modus
```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` verwenden. Es hält Ghidra und sein Projekt als einen lang laufenden Server am Leben und funktioniert sowohl mit MCP-Hosts als auch mit dem CLI-Client.
- **GUI-Modus**: `pyghidra-mcp` startet Ghidra, öffnet das Projekt und stellt zusätzliche Tools bereit, die den CodeBrowser in derselben JVM steuern.
- **CLI-Client**: `pyghidra-mcp-cli` ist ein HTTP-Client. Zuerst einen `streamable-http`-Server starten, dann Terminalbefehle gegen diesen laufenden Server absetzen.
- **stdio**: nur für MCP-Hosts beibehalten, die keine Verbindung zu einem HTTP-Endpunkt herstellen können.
<details>
<summary>Detaillierte Architektur und Tool-Oberfläche</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>
## Inhalt
- [PyGhidra-MCP - Ghidra Model Context Protocol Server](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Überblick](#overview)
- [Noch ein Ghidra MCP?](#yet-another-ghidra-mcp)
- [Setup-Diagramme](#setup-diagrams)
- [Wie die Teile zusammenhängen](#how-the-pieces-connect)
- [Auswahl eines Modus](#choosing-a-mode)
- [Inhalt](#contents)
- [Erste Schritte](#getting-started)
- [Optimiert für Agenten](#optimized-for-agents)
- [CLI-Client](#cli-client)
- [Installation](#installation)
- [Schnellstart mit CLI](#quick-start-with-cli)
- [Projekterstellung, -verwaltung und Öffnen bestehender Projekte](#project-creation-management-and-opening-existing-projects)
- [Neue Projekte erstellen](#creating-new-projects)
- [Eigenständige Projektstruktur](#self-contained-project-structure)
- [Grundlegende Projekterstellung](#basic-project-creation)
- [Benutzerdefinierte Projekterstellung](#custom-project-creation)
- [Mehrere zusammenhängende Projekte erstellen](#creating-multiple-related-projects)
- [Bestehende Ghidra-Projekte öffnen](#opening-existing-ghidra-projects)
- [Öffnen über .gpr-Datei](#opening-by-gpr-file)
- [GUI-Modus](#gui-mode)
- [Startvorgaben und große Projekte](#startup-defaults-and-large-projects)
- [Entwicklung](#development)
- [Einrichtung](#setup)
- [Testen und Qualität](#testing-and-quality)
- [API](#api)
- [Werkzeuge](#tools)
- [Batch-Operationen](#batch-operations)
- [Lese-/Analysewerkzeuge](#read--analysis-tools)
- [Projektoperationen](#project-operations)
- [Bearbeitungs-/Mutationswerkzeuge](#edit--mutation-tools)
- [GUI-Steuerungswerkzeuge (nur `--gui`)](#gui-control-tools---gui-only)
- [Verwendung](#usage)
- [Binärdateien mit Docker einbinden](#mapping-binaries-with-docker)
- [Streamable HTTP](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Standard Input/Output (stdio)](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [Verwendung mit OpenWeb-UI und MCPO](#using-with-openweb-ui-and-mcpo)
- [Mit `uvx`](#with-uvx)
- [Mit Docker](#docker-2)
- [Server-sent events (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Inspiration](#inspiration)
- [Mitwirken, Community und Ausführung aus dem Quellcode](#contributing-community-and-running-from-source)
- [Beitragenden-Workflow](#contributor-workflow)
## Erste Schritte
Starten Sie einen persistenten Streamable HTTP-Server mit dem [Python-Paket](https://pypi.org/p/pyghidra-mcp) und [`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
```
Der Server ist dann unter `http://127.0.0.1:8000/mcp` verfügbar. Lass ihn laufen und konfiguriere deinen MCP-Client so, dass er diese URL verwendet; die Beispiele für [Claude Code](#claude-code) und [Codex](#codex) unten zeigen die erwartete Konfiguration.
Um eine laufende Ghidra-GUI über MCP zu starten und zu steuern, verwende `--gui` zusammen mit `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` startet Ghidra über `pyghidra-mcp`. Es wird keine Verbindung zu einer bereits laufenden externen Ghidra-Instanz hergestellt.
Oder als [Docker-Container](https://ghcr.io/clearbluejar/pyghidra-mcp) ausführen:
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Optimiert für Agenten
`pyghidra-mcp` hält die MCP-Oberfläche bewusst schmal, damit Agenten-Clients weniger Tokens für die Tool-Erkennung und Argumentauswahl aufwenden müssen.
- **Kurze Tool-Beschreibungen**: MCP-Tool-Docstrings werden kompakt gehalten, damit die Tool-Schemas des MCPServers klein bleiben und kostengünstig an Modelle gesendet werden können.
- **Kontextdisziplin**: Tools liefern fokussierte strukturierte Daten zurück, anstatt standardmäßig den gesamten Programmkontext auszugeben. Dekompilierungs-, Symbolsuch- und Querverweisergebnisse sind so gestaltet, dass sie eine iterative Analyse unterstützen, statt einer einzigen großen Antwort.
- **GUI-Tools nur wenn relevant**: GUI-only-Steuerelemente wie `open_program_in_gui`, `list_open_programs`, `set_current_program` und `goto` werden nur bereitgestellt, wenn der Server mit `--gui` gestartet wird.
- **CLI ist optional**: Wenn MCP nicht Ihre bevorzugte Schnittstelle ist, bietet `pyghidra-mcp-cli` einen direkten Kommandozeilen-Client über HTTP mit gruppierten Befehlen für gängige Bearbeitungs- und Analyse-Workflows.
Dadurch bleibt der Standard-Server für LLM-Agenten, IDE-Integrationen und Automatisierung nutzbar, ohne unnötige Tool-Oberfläche oder GUI-only-Steuerelemente in Headless-Sitzungen offenzulegen.
## CLI-Client
Für eine interaktivere Kommandozeilen-Erfahrung können Sie das separate Paket **pyghidra-mcp-cli** verwenden, das eine benutzerfreundliche Schnittstelle für die Interaktion mit einem laufenden pyghidra-mcp-Server bietet.
### Installation
Installieren Sie den CLI-Client mit [`uv`](https://docs.astral.sh/uv/) (empfohlen):
```bash
uvx pyghidra-mcp-cli
```
Oder mit pip installieren:
```bash
pip install pyghidra-mcp-cli
```
### Schnellstart mit CLI
1. **Server starten** (in einem Terminal):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **Verwenden Sie die CLI** (in einem anderen Terminal):
```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]
> Die CLI verbindet sich über HTTP mit pyghidra-mcp, um den Startaufwand von 10-60 Sekunden zu vermeiden, der durch das Starten eines neuen Ghidra-Prozesses für jeden Befehl entsteht. Siehe die [CLI README](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) für die vollständige Dokumentation.
## Projekterstellung, -verwaltung und Öffnen bestehender Projekte
### Neue Projekte erstellen
Sie können neue Projekte auf verschiedene Arten erstellen, je nach Ihrem Workflow:
#### Eigenständige Projektstruktur
`pyghidra-mcp` erstellt eine **eigenständige Projektstruktur**, bei der jedes Projekt sein eigenes Ghidra-Projekt und eigene pyghidra-mcp-Artefakte hat. Dies gewährleistet vollständige Isolation und einfache Projektverwaltung.
#### Grundlegende Projekterstellung
```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
```
#### Benutzerdefinierte Projekterstellung
```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
```
#### Mehrere zusammenhängende Projekte erstellen
```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
```
### Öffnen bestehender Ghidra-Projekte
Wenn Sie bestehende Ghidra-Projekte (`.gpr`-Dateien) haben, können Sie diese direkt mit `pyghidra-mcp` öffnen:
#### Öffnen über .gpr-Datei
```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-Modus
Verwenden Sie den GUI-Modus, wenn MCP-Aktionen auf dieselben Live-Programmobjekte wirken sollen, die Ghidra anzeigt.
- `--gui` erfordert `--transport streamable-http` (oder `--transport http` als Alias)
- `--project-path` kann ein Projektverzeichnis plus `--project-name` sein oder eine vorhandene `.gpr`-Datei. Fehlende Projekte werden automatisch erstellt.
- Ghidra wird von `pyghidra-mcp` gestartet, wodurch GUI- und MCP-Transaktionen in derselben JVM bleiben
- Nur-GUI-Tools werden nur bei Ausführung mit `--gui` bereitgestellt
Beispiel:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
Der GUI-Modus ist die richtige Wahl, wenn Sie:
- Programme in CodeBrowser öffnen oder wechseln möchten
- im Listing zu einer Funktion oder Adresse navigieren möchten
- Funktionen umbenennen oder Kommentare hinzufügen möchten und diese Änderungen sofort in Ghidra sehen möchten
### Startvorgaben und große Projekte
`pyghidra-mcp` erfordert standardmäßig kein `--wait-for-analysis`. Der Server kann starten, während die Analyse und die MCP-seitige Indizierung im Hintergrund weiterlaufen.
Dies ist bei großen Projekten wichtig:
- das Starten eines Projekts mit vielen Binärdateien muss den Serverstart nicht blockieren
- `--wait-for-analysis` ist verfügbar, wenn Sie ein vollständig analysiertes Projekt wünschen, bevor Anfragen bedient werden
- bei großen bestehenden Projekten variiert die Bereitschaft von Analyse und Indizierung je nach Binärdatei
Aktuelle Einschränkung:
- der Ghidra-Analysestatus und der MCP-Indizierungsstatus sind getrennt
- eine Binärdatei kann in Ghidra vollständig analysiert sein, während `search_strings` oder die semantische `search_code` noch auf die MCP-seitige Indizierung warten
- dies fällt stärker auf, wenn größere bestehende Projekte geöffnet werden
In der Praxis:
- Dekompilierung, Navigation, Umbenennung und Kommentare können für eine Binärdatei weiterhin funktionieren, während indizierungsintensive Suchfunktionen noch aufholen
- wenn die Startlatenz wichtiger ist als die sofortige Suchbereitschaft, behalten Sie den Standard `--no-wait-for-analysis` bei
- wenn die sofortige Bereitschaft wichtiger ist als die Startzeit, verwenden Sie `--wait-for-analysis`
## Entwicklung
Dieses Projekt verwendet ein `Makefile`, um Entwicklung und Tests zu optimieren. `ruff` wird zum Linting und Formatieren verwendet, und `pre-commit`-Hooks werden eingesetzt, um die Codequalität sicherzustellen.
### Einrichtung
1. **`uv` installieren**: Wenn Sie `uv` nicht installiert haben, können Sie es mit pip installieren:
```bash
pip install uv
```
Oder folgen Sie der offiziellen `uv`-Installationsanleitung: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **Eine virtuelle Umgebung erstellen und Abhängigkeiten installieren**:
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **Ghidra-Umgebungsvariable setzen**: Laden Sie Ghidra herunter und installieren Sie es, und setzen Sie dann die Umgebungsvariable `GHIDRA_INSTALL_DIR` auf Ihr Ghidra-Installationsverzeichnis.
```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)
```
### Testen und Qualität
Das `Makefile` bietet mehrere Targets für Tests und Codequalität:
- `make run`: Den MCP-Server ausführen.
- `make test`: Die vollständige Testsuite ausführen (Unit- und Integrationstests).
- `make test-unit`: Unit-Tests ausführen.
- `make test-integration`: Integrationstests ausführen.
- `make test-integration-fast`: Den leichten Integration-Smoke-Test ausführen, der von pre-commit verwendet wird.
- `make test-integration-gui`: GUI-Integrationstests ausführen. Erfordert eine funktionierende Ghidra-Installation und GUI-Unterstützung.
- `make lint`: Den Codestil mit `ruff` prüfen.
- `make format`: Den Code mit `ruff` formatieren.
- `make typecheck`: Leichte statische Prüfungen mit `ruff` ausführen.
- `make check`: Alle Qualitätsprüfungen ausführen.
- `make dev`: Den Entwicklungs-Workflow ausführen (Formatieren und Prüfen).
- `make build`: Distributionspakete erstellen.
- `make clean`: Build-Artefakte und Cache bereinigen.
Empfohlene Aufteilung:
- pre-commit: `ruff`, `pyright`, Unit-Tests und ein leichter Integration-Smoke-Test
- GitHub Actions: vollständige Linux-Headless-Integrationsabdeckung, Linux-GUI unter `Xvfb`, CLI-Abdeckung und aktuelle macOS-Smoke-Tests
- geplante CI: Kompatibilitätsabdeckung für ältere macOS- / Ghidra-Versionen
- lokal/manuell: aufwändigeres umgebungsspezifisches GUI-Debugging und Release-Sanity-Checks
## API
### Tools
LLMs in die Lage versetzen, Aktionen auszuführen, deterministische Berechnungen durchzuführen und mit externen Diensten zu interagieren.
#### Batch-Operationen
`decompile_function` und `list_xrefs` akzeptieren ein einzelnes Ziel oder eine Liste von Zielen, wodurch Round-Trips bei der Analyse von Aufrufketten oder mehreren Symbolen gleichzeitig reduziert werden.
```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"]
}
```
Fehler pro Element werden inline zurückgegeben (andere Ziele sind weiterhin erfolgreich):
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### Lese-/Analysewerkzeuge
- `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)`: Durchsucht dekompilierten Pseudo-C-Code mithilfe semantischer Vektorsuche oder wörtlichem Abgleich.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Listet Querverweise auf Funktion(en), Symbol(e) oder Adresse(n) auf. Akzeptiert ein einzelnes Ziel oder eine Liste für die Stapelabfrage.
- `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)`: Erzeugt einen MermaidJS-Aufrufgraphen für eine angegebene Funktion. Unterstützt sowohl die Richtungen "calling" (Funktionen, die vom Ziel aufgerufen werden) als auch "called" (Funktionen, die das Ziel aufrufen) mit mehreren Visualisierungstypen.
- `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)`: Dekompiliert Funktion(en) nach Name oder Adresse. Akzeptiert ein einzelnes Ziel oder eine Liste für die Stapel-Dekompilierung. Umfangreiche Antwort-Flags hängen Callees, Strings und/oder Xrefs an jedes Ergebnis an. `timeout_sec` gilt pro Ziel und begrenzt jeden Dekompilierungsversuch unabhängig.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Listet alle exportierten Funktionen und Symbole aus einer angegebenen Binärdatei auf (Regex für die Abfrage unterstützt).
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Listet alle importierten Funktionen und Symbole für eine angegebene Binärdatei auf (Regex für die Abfrage unterstützt).
- `read_bytes(binary_name: str, address: str, size: int = 32)`: Liest Rohbytes aus dem Speicher an einer angegebenen Adresse. Hex-Adressen können das Präfix `0x` enthalten oder weglassen.
- `search_strings(binary_name: str, query: str, limit: int = 100)`: Durchsucht Strings innerhalb einer Binärdatei.
- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Sucht Symbole innerhalb einer Binärdatei nach Namen. Unterstützt Regex-Muster (z. B. `^main$`, `func.*one`) mit Groß-/Kleinschreibung-unabhängigem Abgleich oder einfache Teilstring-Abfragen. Setzen Sie `functions_only=True`, um Labels, Variablen und andere Nicht-Funktions-Symbole auszuschließen.
#### Projektoperationen
- `import_binary(binary_path: str)`: Importiert eine Binärdatei von einem angegebenen Pfad in das aktuelle Ghidra-Projekt. Wenn der Pfad ein Verzeichnis ist, wird es rekursiv durchsucht und alle unterstützten Binärdateien importiert, wobei die Verzeichnisstruktur innerhalb des Ghidra-Projekts erhalten bleibt.
- `list_project_binaries()`: Listet Binärdateien im aktuellen Ghidra-Projekt auf. Im GUI-Modus umfasst dies Projekt-Binärdateien, die auf der Festplatte vorhanden sind, auch wenn sie derzeit nicht im CodeBrowser geöffnet sind.
- `list_project_binary_metadata(binary_name: str)`: Ruft detaillierte Metadaten für eine bestimmte Binärdatei ab, einschließlich Architektur, Compiler, ausführbares Format, Analysemetriken und Dateihashes.
- `delete_project_binary(binary_name: str)`: Löscht eine Binärdatei (Programm) aus dem Ghidra-Projekt.
#### Bearbeitungs-/Mutationswerkzeuge
- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Benennt eine Funktion nach Name oder Adresse um. Im GUI-Modus läuft dies als Live-Ghidra-Transaktion und aktualisiert das geöffnete Programm.
- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Benennt einen Funktionsparameter oder eine lokale Variable nach exaktem Namen innerhalb einer bestimmten Funktion um. Wenn der Name fehlt oder innerhalb dieser Funktion mehrdeutig ist, gibt das Werkzeug einen Fehler zurück, anstatt zu raten. Im GUI-Modus läuft dies als Live-Ghidra-Transaktion und aktualisiert das geöffnete Programm.
- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Legt den Datentyp für einen Funktionsparameter oder eine lokale Variable nach exaktem Namen innerhalb einer bestimmten Funktion fest. Wenn der Name fehlt oder innerhalb dieser Funktion mehrdeutig ist, gibt das Werkzeug einen Fehler zurück, anstatt zu raten. `type_name` wird mit Ghidras Datentyp-Parser gegen den Programm-Datentyp-Manager geparst.
- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Legt einen Funktionsprototyp aus einer vollständigen Signaturzeichenfolge fest. Das Werkzeug führt den Prototyp immer durch Ghidras nativen Signatur-Parser und gibt den zugrunde liegenden Parser- oder Anwendungsfehler zurück, wenn der Prototyp ungültig ist.
- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Legt einen Funktions-/Dekompiliererkommentar oder Listing-Kommentar fest. Listing-Kommentarziele können Adressen, Symbole oder Funktionen sein. Unterstützte `comment_type`-Werte sind `decompiler`, `plate`, `pre`, `eol`, `post` und `repeatable`.
#### GUI-Steuerungswerkzeuge (nur `--gui`)
Diese Werkzeuge sind nur verfügbar, wenn `pyghidra-mcp` mit `--gui` gestartet wird, und steuern, was die GUI anzeigt, anstatt Projektdaten direkt zu verändern:
- `list_open_programs()`: Listet Programme auf, die derzeit in der Ghidra-GUI geöffnet sind.
- `open_program_in_gui(binary_name: str, new_window: bool = True)`: Öffnet eine Projekt-Binärdatei im CodeBrowser. Standardmäßig wird ein neues CodeBrowser-Fenster geöffnet. Setzen Sie `new_window=false`, um nach Möglichkeit einen sichtbaren CodeBrowser wiederzuverwenden.
- `set_current_program(binary_name: str)`: Macht ein geöffnetes Programm zum aktiven/aktuellen Programm im primären GUI-Werkzeugkontext.
- `goto(binary_name: str, target: str, target_type: str)`: Navigiert die Ghidra-GUI zu einer Adresse oder Funktion. `target_type` muss `address` oder `function` sein.
## Verwendung
Dieses Python-Paket wird als [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) auf PyPI veröffentlicht und kann mit [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/) oder einem beliebigen Python-Paketmanager installiert und ausgeführt werden.
```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.
```
### Binärdateien mit Docker einbinden
Bei Verwendung des Docker-Containers können Sie ein lokales Verzeichnis mit Ihren Binärdateien in den Arbeitsbereich des Containers einbinden. Dadurch kann `pyghidra-mcp` Ihre Dateien analysieren.
```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
Streamable HTTP ist der empfohlene Transport. Er hält einen Ghidra-Prozess und ein Projekt für MCP-Hosts und `pyghidra-mcp-cli` verfügbar und vermeidet die Startkosten eines separaten Prozesses pro Client. Er sendet JSON-RPC-Anfragen über HTTP; siehe die [Spezifikation](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) für Details.
Standardmäßig lauscht der Server auf [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) auf Client-Verbindungen. Verwenden Sie `--host` / `--port` oder die Umgebungsvariablen `MCP_HOST` / `MCP_PORT`, um die Bind-Adresse zu ändern. _Der Server muss laufen, damit Clients sich mit ihm verbinden können._
#### Python
```bash
pyghidra-mcp -t streamable-http
```
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)