Python Ghidra MCP da riga di comando
<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 - Server Model Context Protocol per Ghidra
### Panoramica
**`pyghidra-mcp`** è un server Model Context Protocol (MCP) da riga di comando che porta tutta la potenza analitica di [Ghidra](https://ghidra-sre.org/), una solida suite di reverse engineering del software (SRE), nel mondo degli agenti intelligenti e degli strumenti basati su LLM.
Collega le [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) e [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) di Ghidra a Python usando `pyghidra` e `jpype`, per poi esporre tale funzionalità tramite il Model Context Protocol.
MCP è un'interfaccia unificata che consente a modelli linguistici, strumenti di sviluppo (come VS Code) e agenti autonomi di accedere a contesto strutturato, invocare strumenti e collaborare in modo intelligente. Pensate a MCP come al ponte tra potenti strumenti di analisi e l'ecosistema degli LLM.
Con `pyghidra-mcp`, Ghidra diventa un backend intelligente—pronto a rispondere a query ricche di contesto, automatizzare attività di reverse engineering approfondite e integrarsi in flussi di lavoro assistiti dall'IA.
`pyghidra-mcp` ora supporta due modalità operative:
- modalità `headless` per analisi e automazione guidate da CLI
- modalità `--gui`, che avvia Ghidra tramite `pyghidra-mcp` e condivide lo stato del programma in tempo reale con la GUI in esecuzione
> [!NOTE]
> Questo progetto beta è in fase di sviluppo attivo. Gradiremmo il vostro feedback, segnalazioni di bug, richieste di funzionalità e codice.
## L'ennesimo Ghidra MCP?
Sì, l'originale [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) è fantastico. Ma `pyghidra-mcp` adotta un approccio diverso:
- 🐍 **Headless-first, GUI-capable** – Eseguibile interamente via CLI per un'automazione snella, oppure avvia Ghidra con `--gui` quando desideri navigazione ed editing in tempo reale tramite GUI.
- 🔁 **Progettato per l'automazione** – Ideale per l'integrazione con LLM, pipeline CI e strumenti che richiedono un comportamento ripetibile.
- ✅ **Compatibile con CI/CD** – Costruito con solidi test unitari e di integrazione sia per le sessioni client che server.
- 🚀 **Avvio rapido** – L'avvio asincrono consente al server di iniziare a gestire richieste mentre i binari sono ancora in fase di analisi in background. Supporta l'avvio rapido da riga di comando con configurazione minima.
- 📦 **Analisi a livello di progetto** – Consente il reverse engineering concorrente di tutti i binari in un progetto Ghidra
- 🤖 **Pronto per gli agenti** – Costruito per flussi di lavoro guidati da agenti intelligenti e automazione del reverse engineering su larga scala.
- 🔍 Ricerca semantica del codice – Utilizza embedding vettoriali (tramite ChromaDB) per consentire una ricerca rapida e fuzzy tra funzioni decompilate, commenti e simboli—perfetto per l'esplorazione di pseudo-C e il triage guidato da agenti.
Questo progetto offre un'esperienza Python-first ottimizzata per lo sviluppo locale, ambienti headless e flussi di lavoro testabili.
## Diagrammi di configurazione
### Come si collegano i componenti
```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
```
### Scegliere una Modalità
```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**: usa `streamable-http`. Mantiene Ghidra e il suo progetto attivi come un unico server a esecuzione prolungata e funziona sia con host MCP sia con il client CLI.
- **Modalità GUI**: `pyghidra-mcp` avvia Ghidra, apre il progetto ed espone strumenti aggiuntivi che guidano il CodeBrowser nella stessa JVM.
- **Client CLI**: `pyghidra-mcp-cli` è un client HTTP. Avvia prima un server `streamable-http`, poi invia comandi da terminale a quel server in esecuzione.
- **stdio**: mantienilo solo per gli host MCP che non possono connettersi a un endpoint HTTP.
<details>
<summary>Architettura dettagliata e superficie degli strumenti</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>
## Contenuti
- [PyGhidra-MCP - Server Model Context Protocol per Ghidra](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Panoramica](#panoramica)
- [Ancora un altro Ghidra MCP?](#ancora-un-altro-ghidra-mcp)
- [Diagrammi di configurazione](#diagrammi-di-configurazione)
- [Come si collegano i componenti](#come-si-collegano-i-componenti)
- [Scegliere una modalità](#scegliere-una-modalità)
- [Contenuti](#contenuti)
- [Per iniziare](#per-iniziare)
- [Ottimizzato per gli agenti](#ottimizzato-per-gli-agenti)
- [Client CLI](#client-cli)
- [Installazione](#installazione)
- [Avvio rapido con la CLI](#avvio-rapido-con-la-cli)
- [Creazione, gestione e apertura di progetti esistenti](#creazione-gestione-e-apertura-di-progetti-esistenti)
- [Creazione di nuovi progetti](#creazione-di-nuovi-progetti)
- [Struttura del progetto autocontenuto](#struttura-del-progetto-autocontenuto)
- [Creazione di base di un progetto](#creazione-di-base-di-un-progetto)
- [Creazione personalizzata di un progetto](#creazione-personalizzata-di-un-progetto)
- [Creazione di più progetti correlati](#creazione-di-più-progetti-correlati)
- [Apertura di progetti Ghidra esistenti](#apertura-di-progetti-ghidra-esistenti)
- [Apertura tramite file .gpr](#apertura-tramite-file-gpr)
- [Modalità GUI](#modalità-gui)
- [Valori predefiniti di avvio e progetti di grandi dimensioni](#valori-predefiniti-di-avvio-e-progetti-di-grandi-dimensioni)
- [Sviluppo](#sviluppo)
- [Configurazione](#configurazione)
- [Test e qualità](#test-e-qualità)
- [API](#api)
- [Strumenti](#strumenti)
- [Operazioni in batch](#operazioni-in-batch)
- [Strumenti di lettura / analisi](#strumenti-di-lettura--analisi)
- [Operazioni sui progetti](#operazioni-sui-progetti)
- [Strumenti di modifica / mutazione](#strumenti-di-modifica--mutazione)
- [Strumenti di controllo GUI (solo `--gui`)](#strumenti-di-controllo-gui-solo---gui)
- [Utilizzo](#utilizzo)
- [Mappatura dei binari con Docker](#mappatura-dei-binari-con-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)
- [Utilizzo con OpenWeb-UI e MCPO](#utilizzo-con-openweb-ui-e-mcpo)
- [Con `uvx`](#con-uvx)
- [Con Docker](#docker-2)
- [Server-sent events (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Ispirazione](#ispirazione)
- [Contribuire, community ed esecuzione dal sorgente](#contribuire-community-ed-esecuzione-dal-sorgente)
- [Flusso di lavoro del contributore](#flusso-di-lavoro-del-contributore)
## Per iniziare
Avvia un server Streamable HTTP persistente utilizzando il [pacchetto Python](https://pypi.org/p/pyghidra-mcp) e [`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
```
Il server è quindi disponibile all'indirizzo `http://127.0.0.1:8000/mcp`. Lascialo in esecuzione e configura il tuo client MCP per utilizzare quell'URL; gli esempi [Claude Code](#claude-code) e [Codex](#codex) riportati di seguito mostrano la configurazione prevista.
Per avviare e controllare una GUI Ghidra attiva da MCP, usa `--gui` con `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` avvia Ghidra tramite `pyghidra-mcp`. Non si collega a un'istanza Ghidra esterna già in esecuzione.
Oppure, eseguilo come [container Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Ottimizzato per gli Agenti
`pyghidra-mcp` mantiene la superficie MCP intenzionalmente ristretta in modo che i client degli agenti spendano meno token per la scoperta degli strumenti e la selezione degli argomenti.
- **Descrizioni brevi degli strumenti**: le docstring degli strumenti MCP sono mantenute compatte in modo che gli schemi degli strumenti MCPServer rimangano piccoli ed economici da inviare ai modelli.
- **Disciplina del contesto**: gli strumenti restituiscono dati strutturati e mirati invece di scaricare l'intero contesto del programma per impostazione predefinita. I risultati di decompilazione, ricerca dei simboli e riferimenti incrociati sono modellati per supportare l'analisi iterativa anziché una singola risposta di grandi dimensioni.
- **Strumenti GUI solo quando pertinenti**: i controlli solo GUI come `open_program_in_gui`, `list_open_programs`, `set_current_program` e `goto` sono esposti solo quando il server viene avviato con `--gui`.
- **CLI è opzionale**: se MCP non è la tua interfaccia preferita, `pyghidra-mcp-cli` fornisce un client diretto da riga di comando su HTTP con comandi raggruppati per i comuni flussi di lavoro di modifica e analisi.
Questo mantiene il server predefinito utilizzabile per agenti LLM, integrazioni IDE e automazione senza esporre una superficie di strumenti non necessaria o controlli solo GUI in sessioni headless.
## Client CLI
Per un'esperienza da riga di comando più interattiva, puoi utilizzare il pacchetto separato **pyghidra-mcp-cli**, che fornisce un'interfaccia intuitiva per interagire con un server pyghidra-mcp in esecuzione.
### Installazione
Installa il client CLI utilizzando [`uv`](https://docs.astral.sh/uv/) (consigliato):
```bash
uvx pyghidra-mcp-cli
```
Oppure installa con pip:
```bash
pip install pyghidra-mcp-cli
```
### Avvio rapido con la CLI
1. **Avvia il server** (in un terminale):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **Usa la CLI** (in un altro terminale):
```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]
> La CLI si connette a pyghidra-mcp tramite HTTP per evitare il sovraccarico di avvio di 10-60 secondi dovuto all'avvio di un nuovo processo Ghidra per ogni comando. Consulta il [README della CLI](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) per la documentazione completa.
## Creazione, gestione e apertura di progetti esistenti
### Creazione di nuovi progetti
Puoi creare nuovi progetti in diversi modi, a seconda del tuo flusso di lavoro:
#### Struttura di progetto autonoma
`pyghidra-mcp` crea una **struttura di progetto autonoma** in cui ogni progetto ha il proprio progetto Ghidra e i propri artefatti pyghidra-mcp. Questo garantisce un isolamento completo e una facile gestione dei progetti.
#### Creazione di base di un progetto
```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
```
#### Creazione di un progetto personalizzato
```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
```
#### Creazione di più progetti correlati
```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
```
### Apertura di progetti Ghidra esistenti
Se hai progetti Ghidra esistenti (file `.gpr`), puoi aprirli direttamente con `pyghidra-mcp`:
#### Apertura tramite file .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)
```
### Modalità GUI
Usa la modalità GUI quando vuoi che le azioni MCP operino sugli stessi oggetti di programma live che Ghidra sta visualizzando.
- `--gui` richiede `--transport streamable-http` (o `--transport http` come alias)
- `--project-path` può essere una directory di progetto più `--project-name`, oppure un file `.gpr` esistente. I progetti mancanti vengono creati automaticamente.
- Ghidra viene avviato da `pyghidra-mcp`, che mantiene le transazioni GUI e MCP nella stessa JVM
- Gli strumenti solo GUI sono esposti solo quando si esegue con `--gui`
Esempio:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
La modalità GUI è la scelta giusta quando vuoi:
- aprire o cambiare programma in CodeBrowser
- navigare il listing fino a una funzione o a un indirizzo
- rinominare funzioni o aggiungere commenti e vedere immediatamente tali modifiche in Ghidra
### Valori predefiniti all'avvio e progetti di grandi dimensioni
`pyghidra-mcp` non richiede `--wait-for-analysis` per impostazione predefinita. Il server può avviarsi mentre l'analisi e l'indicizzazione lato MCP continuano in background.
Questo è importante per i progetti di grandi dimensioni:
- avviare un progetto con molti binari non deve bloccare l'avvio del server
- `--wait-for-analysis` è disponibile quando vuoi un progetto completamente analizzato prima di servire le richieste
- per progetti esistenti di grandi dimensioni, aspettati che la disponibilità dell'analisi e dell'indicizzazione vari da binario a binario
Limitazione attuale:
- lo stato dell'analisi di Ghidra e lo stato dell'indicizzazione MCP sono separati
- un binario può essere completamente analizzato in Ghidra mentre `search_strings` o `search_code` semantico sono ancora in attesa dell'indicizzazione lato MCP
- questo è più evidente quando si aprono progetti esistenti di grandi dimensioni
In pratica:
- la decompilazione, la navigazione, la rinomina e i commenti possono ancora funzionare per un binario mentre le funzionalità di ricerca ad alta intensità di indicizzazione stanno recuperando
- se la latenza di avvio conta più della disponibilità immediata della ricerca, mantieni il valore predefinito `--no-wait-for-analysis`
- se la disponibilità immediata conta più del tempo di avvio, usa `--wait-for-analysis`
## Sviluppo
Questo progetto utilizza un `Makefile` per semplificare lo sviluppo e il testing. `ruff` è usato per il linting e la formattazione, e gli hook `pre-commit` sono usati per garantire la qualità del codice.
### Configurazione
1. **Installa `uv`**: Se non hai `uv` installato, puoi installarlo usando pip:
```bash
pip install uv
```
Oppure, segui la guida ufficiale all'installazione di `uv`: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **Crea un ambiente virtuale e installa le dipendenze**:
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **Imposta la variabile d'ambiente di Ghidra**: Scarica e installa Ghidra, poi imposta la variabile d'ambiente `GHIDRA_INSTALL_DIR` sulla directory di installazione di Ghidra.
```bash
# For Linux / Mac
export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
# For Windows PowerShell
[System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/main/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
```
### Testing e qualità
Il `Makefile` fornisce diversi target per il testing e la qualità del codice:
- `make run`: Avvia il server MCP.
- `make test`: Esegue l'intera suite di test (unit e integration).
- `make test-unit`: Esegue i test unitari.
- `make test-integration`: Esegue i test di integrazione.
- `make test-integration-fast`: Esegue il test di smoke di integrazione leggero usato da pre-commit.
- `make test-integration-gui`: Esegue i test di integrazione GUI. Richiede un'installazione funzionante di Ghidra e il supporto GUI.
- `make lint`: Controlla lo stile del codice con `ruff`.
- `make format`: Formatta il codice con `ruff`.
- `make typecheck`: Esegue controlli statici leggeri con `ruff`.
- `make check`: Esegue tutti i controlli di qualità.
- `make dev`: Esegue il flusso di lavoro di sviluppo (format e check).
- `make build`: Crea i pacchetti di distribuzione.
- `make clean`: Pulisce gli artefatti di build e la cache.
Suddivisione consigliata:
- pre-commit: `ruff`, `pyright`, test unitari e un test di smoke di integrazione leggero
- GitHub Actions: copertura completa dell'integrazione Linux headless, GUI Linux sotto `Xvfb`, copertura CLI e attuali test di smoke su macOS
- CI pianificata: copertura di compatibilità con versioni precedenti di macOS / Ghidra
- locale/manuale: debug GUI più pesante specifico per l'ambiente e controlli di sanità per il rilascio
## API
### Strumenti
Consentono agli LLM di eseguire azioni, effettuare calcoli deterministici e interagire con servizi esterni.
#### Operazioni in batch
`decompile_function` e `list_xrefs` accettano un singolo target o una lista di target, riducendo i round-trip quando si analizzano catene di chiamate o più simboli contemporaneamente.
```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"]
}
```
Gli errori per singolo elemento vengono restituiti inline (gli altri target hanno comunque successo):
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### Strumenti di Lettura / Analisi
- `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)`: Cerca nel pseudo-C decompilato utilizzando la ricerca vettoriale semantica o la corrispondenza letterale.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Elenca i riferimenti incrociati a funzione/i, simbolo/i o indirizzo/i. Accetta un singolo target o una lista per la ricerca in batch.
- `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)`: Genera un grafo di chiamate MermaidJS per una funzione specificata. Supporta sia la direzione "calling" (funzioni chiamate dal target) che "called" (funzioni che chiamano il target) con molteplici tipi di visualizzazione.
- `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)`: Decompila funzione/i per nome o indirizzo. Accetta un singolo target o una lista per la decompilazione in batch. I flag di risposta avanzata allegano callee, stringhe e/o xref a ciascun risultato. `timeout_sec` si applica per target e limita ogni tentativo di decompilazione in modo indipendente.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Elenca tutte le funzioni e i simboli esportati da un binario specificato (regex supportata per la query).
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Elenca tutte le funzioni e i simboli importati per un binario specificato (regex supportata per la query).
- `read_bytes(binary_name: str, address: str, size: int = 32)`: Legge i byte grezzi dalla memoria a un indirizzo specificato. Gli indirizzi esadecimali possono includere o omettere il prefisso `0x`.
- `search_strings(binary_name: str, query: str, limit: int = 100)`: Cerca stringhe all'interno di un binario.
- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Cerca simboli all'interno di un binario per nome. Supporta pattern regex (es. `^main$`, `func.*one`) con corrispondenza case-insensitive, o query di sottostringa semplice. Imposta `functions_only=True` per escludere etichette, variabili e altri simboli non-funzione.
#### Operazioni sul Progetto
- `import_binary(binary_path: str)`: Importa un binario da un percorso designato nel progetto Ghidra corrente. Se il percorso è una directory, eseguirà una scansione ricorsiva e importerà tutti i file binari supportati, preservando la struttura delle directory all'interno del progetto Ghidra.
- `list_project_binaries()`: Elenca i binari nel progetto Ghidra corrente. In modalità GUI questo include i binari del progetto che esistono su disco anche se non sono attualmente aperti in CodeBrowser.
- `list_project_binary_metadata(binary_name: str)`: Recupera metadati dettagliati per un binario specifico, inclusi architettura, compilatore, formato eseguibile, metriche di analisi e hash dei file.
- `delete_project_binary(binary_name: str)`: Elimina un binario (programma) dal progetto Ghidra.
#### Strumenti di Modifica / Mutazione
- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Rinomina una funzione per nome o indirizzo. In modalità GUI questo viene eseguito come transazione Ghidra live e aggiorna il programma aperto.
- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Rinomina un parametro di funzione o una variabile locale per nome esatto all'interno di una funzione specifica. Se il nome è mancante o ambiguo all'interno di quella funzione, lo strumento restituisce un errore invece di indovinare. In modalità GUI questo viene eseguito come transazione Ghidra live e aggiorna il programma aperto.
- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Imposta il tipo di dato per un parametro di funzione o una variabile locale per nome esatto all'interno di una funzione specifica. Se il nome è mancante o ambiguo all'interno di quella funzione, lo strumento restituisce un errore invece di indovinare. `type_name` viene analizzato utilizzando il parser di datatype di Ghidra rispetto al gestore di datatype del programma.
- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Imposta un prototipo di funzione da una stringa di firma completa. Lo strumento esegue sempre il prototipo attraverso il parser di firma nativo di Ghidra e restituisce l'errore del parser o di applicazione sottostante se il prototipo non è valido.
- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Imposta un commento di funzione/decompilatore o un commento di listing. I target dei commenti di listing possono essere indirizzi, simboli o funzioni. I valori supportati per `comment_type` sono `decompiler`, `plate`, `pre`, `eol`, `post` e `repeatable`.
#### Strumenti di Controllo GUI (solo `--gui`)
Questi strumenti sono disponibili solo quando `pyghidra-mcp` viene avviato con `--gui` e controllano ciò che la GUI sta mostrando piuttosto che mutare direttamente i dati del progetto:
- `list_open_programs()`: Elenca i programmi attualmente aperti nella GUI di Ghidra.
- `open_program_in_gui(binary_name: str, new_window: bool = True)`: Apre un binario del progetto in CodeBrowser. Per impostazione predefinita questo apre una nuova finestra di CodeBrowser. Imposta `new_window=false` per riutilizzare un CodeBrowser visibile quando possibile.
- `set_current_program(binary_name: str)`: Rende un programma aperto il programma attivo/corrente nel contesto dello strumento GUI primario.
- `goto(binary_name: str, target: str, target_type: str)`: Naviga la GUI di Ghidra verso un indirizzo o una funzione. `target_type` deve essere `address` o `function`.
## Utilizzo
Questo pacchetto Python è pubblicato su PyPI come [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) e può essere installato ed eseguito con [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/), o qualsiasi gestore di pacchetti 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.
```
### Mappatura dei binari con Docker
Quando si utilizza il container Docker, è possibile mappare una directory locale contenente i propri binari nello workspace del container. Ciò consente a `pyghidra-mcp` di analizzare i file.
```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 è il trasporto consigliato. Mantiene un processo Ghidra e un progetto disponibili per gli host MCP e `pyghidra-mcp-cli`, evitando il costo di avvio di un processo separato per ogni client. Invia richieste JSON-RPC su HTTP; consulta la [spec](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) per i dettagli.
Per impostazione predefinita, il server è in ascolto su [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) per le connessioni dei client. Usa `--host` / `--port` o le variabili d'ambiente `MCP_HOST` / `MCP_PORT` per modificare l'indirizzo di bind. _Il server deve essere in esecuzione affinché i client possano connettersi ad esso._
#### Python
```bash
pyghidra-mcp -t streamable-http
```
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)