> [!IMPORTANT]
> `--gui` startet Ghidra über `pyghidra-mcp`. Es verbindet sich nicht mit einer bereits laufenden externen Ghidra-Instanz.

Oder als [Docker-Container](https://ghcr.io/clearbluejar/pyghidra-mcp) ausführen:```bash
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

Oder mit pip installieren:```bash
pip install pyghidra-mcp-cli

2. **CLI verwenden** (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

#### 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

### Bestehende Ghidra-Projekte öffnen

Wenn Sie bestehende Ghidra-Projekte (`.gpr`-Dateien) haben, können Sie diese direkt mit `pyghidra-mcp` öffnen:

#### Öffnen per .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)

Der GUI-Modus ist die richtige Wahl, wenn du:

- Programme im CodeBrowser öffnen oder wechseln
- im Listing zu einer Funktion oder Adresse navigieren
- Funktionen umbenennen oder Kommentare hinzufügen und diese Änderungen sofort in Ghidra sehen

### Start-Standardwerte und große Projekte

`pyghidra-mcp` erfordert standardmäßig kein `--wait-for-analysis`. Der Server kann starten, während Analyse und MCP-seitige Indizierung im Hintergrund weiterlaufen.

Das ist für große Projekte wichtig:

- Das Starten eines Projekts mit vielen Binaries muss den Serverstart nicht blockieren
- `--wait-for-analysis` ist verfügbar, wenn du ein vollständig analysiertes Projekt möchtest, bevor Anfragen bedient werden
- bei großen bestehenden Projekten ist zu erwarten, dass die Bereitschaft von Analyse und Indizierung je nach Binary variiert

Aktuelle Einschränkung:

- Der Analysezustand von Ghidra und der Indizierungszustand von MCP sind getrennt
- ein Binary kann in Ghidra vollständig analysiert sein, während `search_strings` oder semantisches `search_code` noch auf die MCP-seitige Indizierung warten
- das ist beim Öffnen größerer bestehender Projekte deutlicher spürbar

In der Praxis:

- Dekompilierung, Navigation, Umbenennung und Kommentare können für ein Binary weiterhin funktionieren, während indizierungsintensive Suchfunktionen aufholen
- wenn die Startlatenz wichtiger ist als die sofortige Suchbereitschaft, behalte die Standardeinstellung `--no-wait-for-analysis` bei
- wenn die sofortige Bereitschaft wichtiger ist als die Startzeit, verwende `--wait-for-analysis`


## Entwicklung

Dieses Projekt verwendet ein `Makefile`, um Entwicklung und Tests zu optimieren. `ruff` wird für Linting und Formatierung verwendet, und `pre-commit`-Hooks stellen die Codequalität sicher.

### Einrichtung

1.  **`uv` installieren**: Wenn du `uv` nicht installiert hast, kannst du es mit pip installieren:
    ```bash
    pip install uv
    ```
    Oder folge 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**: Lade Ghidra herunter und installiere es, und setze dann die Umgebungsvariable `GHIDRA_INSTALL_DIR` auf dein 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/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
    ```

### Tests 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 schlanken Integrations-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 Entwicklungsworkflow ausführen (formatieren und prüfen).
- `make build`: Distributionspakete bauen.
- `make clean`: Build-Artefakte und Cache bereinigen.

Empfohlene Aufteilung:

- pre-commit: `ruff`, `pyright`, Unit-Tests und ein schlanker Integrations-Smoke-Test
- GitHub Actions: vollständige Linux-Headless-Integrationstest-Abdeckung, Linux-GUI unter `Xvfb`, CLI-Abdeckung und aktuelle macOS-Smoke-Tests
- geplante CI: Kompatibilitätsabdeckung für ältere macOS-/Ghidra-Versionen
- lokal/manuell: aufwendigeres umgebungsspezifisches GUI-Debugging und Release-Sanity-Checks

## API

### Tools

Ermöglicht LLMs, 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 und reduzieren so die Anzahl der Round-Trips bei der Analyse von Aufrufketten oder mehreren Symbolen gleichzeitig.```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"]
}

#### Lese-/Analysetools

- `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 dekompiliertes Pseudo-C mithilfe von semantischer Vektorsuche oder wörtlicher Übereinstimmung.

- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Listet Querverweise auf Funktion(en), Symbol(e) oder Adresse(n). 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 Richtung „calling" (vom Ziel aufgerufene Funktionen) 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) anhand von Name oder Adresse. Akzeptiert ein einzelnes Ziel oder eine Liste für die Stapeldekompilierung. Umfangreiche Antwort-Flags fügen jedem Ergebnis Callees, Strings und/oder Querverweise hinzu. `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 rohe Bytes aus dem Speicher an einer angegebenen Adresse. Hexadezimale Adressen können das Präfix `0x` enthalten oder weglassen.

- `search_strings(binary_name: str, query: str, limit: int = 100)`: Durchsucht eine Binärdatei nach Zeichenketten.

- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Durchsucht eine Binärdatei nach Symbolen anhand des Namens. Unterstützt Regex-Muster (z. B. `^main$`, `func.*one`) ohne Beachtung der Groß-/Kleinschreibung oder einfache Teilstring-Abfragen. Setzen Sie `functions_only=True`, um Labels, Variablen und andere Nicht-Funktionssymbole 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, werden rekursiv alle unterstützten Binärdateien gescannt und 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 Projektbinä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ührbarem Format, Analysemetriken und Datei-Hashes.

- `delete_project_binary(binary_name: str)`: Löscht eine Binärdatei (ein Programm) aus dem Ghidra-Projekt.

#### Bearbeitungs-/Mutationswerkzeuge

- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Benennt eine Funktion anhand von 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 anhand des exakten Namens innerhalb einer bestimmten Funktion um. Wenn der Name in dieser Funktion fehlt oder mehrdeutig ist, gibt das Werkzeug einen Fehler zurück, statt 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)`: Setzt den Datentyp eines Funktionsparameters oder einer lokalen Variablen anhand des exakten Namens innerhalb einer bestimmten Funktion. Wenn der Name in dieser Funktion fehlt oder mehrdeutig ist, gibt das Werkzeug einen Fehler zurück, statt 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)`: Setzt ein Funktionsprototyp aus einer vollständigen Signaturzeichenkette. Das Werkzeug führt das Prototyp immer durch Ghidras nativen Signatur-Parser aus und gibt den zugrunde liegenden Parser- oder Anwendungsfehler zurück, wenn das Prototyp ungültig ist.

- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Setzt einen Funktions-/Decompiler-Kommentar oder einen Listing-Kommentar. Ziele für Listing-Kommentare 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 Projektbinä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 ist auf PyPI als [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) 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.

### Verwendung mit OpenWeb-UI und MCPO

Sie können `pyghidra-mcp` mit [OpenWeb-UI](https://github.com/open-webui/open-webui) über [MCPO](https://github.com/open-webui/mcpo) integrieren, einen MCP-zu-OpenAPI-Proxy. Dadurch können Sie die Tools von `pyghidra-mcp` über eine standardmäßige RESTful-API bereitstellen und sie so für Webschnittstellen und andere Tools zugänglich machen.

https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95

#### Mit `uvx`

Sie können `pyghidra-mcp` und `mcpo` zusammen mit `uvx` ausführen:```bash
uvx mcpo -- \
  pyghidra-mcp /bin/ls

### Standard-Eingabe/-Ausgabe (stdio)

Der stdio-Transport ermöglicht die Kommunikation über Standard-Eingabe- und -Ausgabeströme. Dies ist besonders nützlich für lokale Integrationen und Kommandozeilen-Tools. Siehe die [Spezifikation](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) für weitere Details.

#### Python```bash
pyghidra-mcp

Standardmäßig startet der Docker-Container den `streamable-http`-Server; geben Sie daher `-t stdio` nach dem Image-Namen an und führen Sie ihn mit `-i` für den [interaktiven](https://docs.docker.com/reference/cli/docker/container/run/#interactive) Stdio-Modus aus.

### Streamable HTTP

Streamable HTTP ermöglicht Streaming-Antworten über JSON RPC mittels HTTP-POST-Anfragen. Weitere Details finden Sie in der [Spezifikation](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http).

Standardmäßig lauscht der Server auf [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) für Clientverbindungen. Verwenden Sie `--host` / `--port` oder die Umgebungsvariablen `MCP_HOST` / `MCP_PORT`, um die Bindungsadresse zu ändern. _Der Server muss ausgeführt werden, damit Clients sich verbinden können._

#### Python```bash
pyghidra-mcp -t streamable-http

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

Standardmäßig läuft das Python-Paket im `stdio`-Modus, daher müssen Sie `-t sse` hinzufügen.

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

## Inspiration

Dieses Projekt wurde in Umsetzung und Design von diesen großartigen Projekten inspiriert:

* [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)

---

## Mitwirken, Community und Ausführung aus dem Quellcode

Wir glauben, dass die Zukunft des Reverse Engineering agentisch, kontextbezogen und skalierbar ist.  
`pyghidra-mcp` ist ein Schritt in diese Zukunft – es macht vollständige Ghidra-Projekte für KI-Agenten und Automatisierungspipelines zugänglich.

Wir entwickeln das Projekt aktiv und freuen uns über Feedback, Issues und Beiträge.

> [!NOTE]
> Wir lieben dein Feedback, Fehlermeldungen, Feature-Wünsche und Code.

### Workflow für Mitwirkende

Wenn du ein neues Tool oder eine neue Integration hinzufügst, ist dies der empfohlene Workflow:

- Beschrifte deinen Branch mit dem Präfix `feature/`, um eine neue Fähigkeit zu kennzeichnen.
- Füge dein Tool im gleichen Stil und mit der gleichen Struktur wie die vorhandenen Tools in `pyghidra/tools/` hinzu.
- Schreibe einen Integrationstest, der dein Tool mit einer `StdioClient`-Instanz ausführt. Platziere ihn in `tests/integration/`.
- Erweitere das parallele Testen, indem du in `tests/integration/test_concurrent_streamable_client.py` einen Aufruf zu deinem Tool hinzufügst.
- Führe `make test` und `make format` aus, um sicherzustellen, dass deine Änderungen alle Tests bestehen und den Linting-Regeln entsprechen.

Dies gewährleistet Konsistenz in der gesamten Codebasis und hilft uns, robuste, skalierbare Werkzeuge für Reverse-Engineering-Workflows zu erhalten.

______________________________________________________________________

Mit ❤️ erstellt vom [PyGhidra-MCP-Team](https://github.com/clearbluejar/pyghidra-mcp)