Ghidra MCP en ligne de commande Python
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/41597/82f9c5eb55db6134d47587275fce66c4ed32b86b5332f7e2d610fa0214070a7f.png" width=60% >
</p>
<p align="center">
<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
</p>
# PyGhidra-MCP - Serveur Model Context Protocol pour Ghidra
### Aperçu
**`pyghidra-mcp`** est un serveur en ligne de commande Model Context Protocol (MCP) qui apporte toute la puissance analytique de [Ghidra](https://ghidra-sre.org/), une suite robuste de rétro-ingénierie logicielle (SRE), dans le monde des agents intelligents et de l'outillage basé sur les LLM.
Il fait le lien entre l'[ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) et l'[FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) de Ghidra et Python via `pyghidra` et `jpype`, puis expose ces fonctionnalités via le Model Context Protocol.
MCP est une interface unifiée qui permet aux modèles de langage, aux outils de développement (comme VS Code) et aux agents autonomes d'accéder à un contexte structuré, d'invoquer des outils et de collaborer intelligemment. Considérez MCP comme le pont entre les outils d'analyse puissants et l'écosystème des LLM.
Avec `pyghidra-mcp`, Ghidra devient un backend intelligent—prêt à répondre à des requêtes riches en contexte, à automatiser des tâches profondes de rétro-ingénierie et à s'intégrer dans des workflows assistés par IA.
`pyghidra-mcp` prend désormais en charge deux modes de fonctionnement :
- mode `headless` pour l'analyse et l'automatisation pilotées par CLI
- mode `--gui`, qui lance Ghidra via `pyghidra-mcp` et partage l'état du programme en direct avec l'interface graphique en cours d'exécution
> [!NOTE]
> Ce projet bêta est en cours de développement actif. Nous serions ravis de recevoir vos retours, rapports de bugs, demandes de fonctionnalités et contributions de code.
## Encore un autre Ghidra MCP ?
Oui, le [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) original est fantastique. Mais `pyghidra-mcp` adopte une approche différente :
- 🐍 **Headless-first, compatible GUI** – Fonctionne entièrement via CLI pour une automatisation rationalisée, ou lance Ghidra avec `--gui` lorsque vous souhaitez une navigation et des modifications en direct dans l'interface graphique.
- 🔁 **Conçu pour l'automatisation** – Idéal pour l'intégration avec les LLM, les pipelines CI et les outils nécessitant un comportement reproductible.
- ✅ **Compatible CI/CD** – Développé avec des tests unitaires et d'intégration robustes pour les sessions client et serveur.
- 🚀 **Démarrage rapide** – Le démarrage asynchrone permet au serveur de commencer à traiter les requêtes pendant que les binaires sont encore analysés en arrière-plan. Prend en charge un lancement rapide en ligne de commande avec une configuration minimale.
- 📦 **Analyse à l'échelle du projet** – Permet la rétro-ingénierie concurrente de tous les binaires d'un projet Ghidra
- 🤖 **Prêt pour les agents** – Conçu pour les workflows pilotés par des agents intelligents et l'automatisation de la rétro-ingénierie à grande échelle.
- 🔍 Recherche sémantique de code – Utilise des embeddings vectoriels (via ChromaDB) pour permettre une recherche rapide et approximative parmi les fonctions décompilées, les commentaires et les symboles—parfait pour l'exploration de pseudo-C et le triage piloté par agent.
Ce projet offre une expérience Python-first optimisée pour le développement local, les environnements headless et les workflows testables.
## Schémas de configuration
### Comment les éléments s'articulent
```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
```
### Choisir un mode
```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"]
```
- **MCP sans interface graphique** : utilisez `streamable-http`. Cela maintient Ghidra et son projet actifs en tant que serveur unique de longue durée et fonctionne à la fois avec les hôtes MCP et le client CLI.
- **Mode GUI** : `pyghidra-mcp` lance Ghidra, ouvre le projet et expose des outils supplémentaires qui pilotent le CodeBrowser dans la même JVM.
- **Client CLI** : `pyghidra-mcp-cli` est un client HTTP. Démarrez d'abord un serveur `streamable-http`, puis émettez des commandes terminal contre ce serveur en cours d'exécution.
- **stdio** : conservez ceci uniquement pour les hôtes MCP qui ne peuvent pas se connecter à un point de terminaison HTTP.
<details>
<summary>Architecture détaillée et surface des outils</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>
## Sommaire
- [PyGhidra-MCP - Serveur Ghidra Model Context Protocol](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Aperçu](#aperçu)
- [Encore un autre Ghidra MCP ?](#encore-un-autre-ghidra-mcp)
- [Schémas d'installation](#schémas-dinstallation)
- [Comment les éléments se connectent](#comment-les-éléments-se-connectent)
- [Choisir un mode](#choisir-un-mode)
- [Sommaire](#sommaire)
- [Pour commencer](#pour-commencer)
- [Optimisé pour les agents](#optimisé-pour-les-agents)
- [Client CLI](#client-cli)
- [Installation](#installation)
- [Démarrage rapide avec la CLI](#démarrage-rapide-avec-la-cli)
- [Création, gestion et ouverture de projets existants](#création-gestion-et-ouverture-de-projets-existants)
- [Création de nouveaux projets](#création-de-nouveaux-projets)
- [Structure de projet autonome](#structure-de-projet-autonome)
- [Création de projet basique](#création-de-projet-basique)
- [Création de projet personnalisée](#création-de-projet-personnalisée)
- [Création de plusieurs projets liés](#création-de-plusieurs-projets-liés)
- [Ouverture de projets Ghidra existants](#ouverture-de-projets-ghidra-existants)
- [Ouverture par fichier .gpr](#ouverture-par-fichier-gpr)
- [Mode GUI](#mode-gui)
- [Valeurs par défaut au démarrage et projets volumineux](#valeurs-par-défaut-au-démarrage-et-projets-volumineux)
- [Développement](#développement)
- [Installation](#installation-1)
- [Tests et qualité](#tests-et-qualité)
- [API](#api)
- [Outils](#outils)
- [Opérations par lots](#opérations-par-lots)
- [Outils de lecture / analyse](#outils-de-lecture--analyse)
- [Opérations sur les projets](#opérations-sur-les-projets)
- [Outils d'édition / mutation](#outils-dédition--mutation)
- [Outils de contrôle GUI (`--gui` uniquement)](#outils-de-contrôle-gui---gui-uniquement)
- [Utilisation](#utilisation)
- [Mappage des binaires avec Docker](#mappage-des-binaires-avec-docker)
- [Streamable HTTP](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Entrée/Sortie standard (stdio)](#entréesortie-standard-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [Utilisation avec OpenWeb-UI et MCPO](#utilisation-avec-openweb-ui-et-mcpo)
- [Avec `uvx`](#avec-uvx)
- [Avec Docker](#docker-2)
- [Server-sent events (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Inspiration](#inspiration)
- [Contribution, communauté et exécution depuis les sources](#contribution-communauté-et-exécution-depuis-les-sources)
- [Flux de travail du contributeur](#flux-de-travail-du-contributeur)
## Pour commencer
Démarrez un serveur Streamable HTTP persistant en utilisant le [paquet Python](https://pypi.org/p/pyghidra-mcp) et [`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
```
Le serveur est alors disponible à l'adresse `http://127.0.0.1:8000/mcp`. Laissez-le en cours d'exécution et configurez votre client MCP pour utiliser cette URL ; les exemples [Claude Code](#claude-code) et [Codex](#codex) ci-dessous montrent la configuration attendue.
Pour lancer et contrôler une interface graphique Ghidra en direct depuis MCP, utilisez `--gui` avec `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` lance Ghidra via `pyghidra-mcp`. Il ne s'attache pas à une instance Ghidra externe déjà en cours d'exécution.
Ou, exécutez-le en tant que [conteneur Docker](https://ghcr.io/clearbluejar/pyghidra-mcp) :
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Optimisé pour les agents
`pyghidra-mcp` maintient une surface MCP volontairement restreinte afin que les clients agents dépensent moins de tokens pour la découverte des outils et la sélection des arguments.
- **Descriptions d'outils courtes** : les docstrings des outils MCP sont gardées compactes afin que les schémas d'outils MCPServer restent petits et peu coûteux à envoyer aux modèles.
- **Discipline de contexte** : les outils renvoient des données structurées ciblées au lieu de déverser par défaut le contexte du programme entier. Les résultats de décompilation, de recherche de symboles et de références croisées sont formatés pour soutenir une analyse itérative plutôt qu'une seule grande réponse.
- **Outils GUI uniquement lorsque pertinent** : les contrôles réservés à la GUI tels que `open_program_in_gui`, `list_open_programs`, `set_current_program` et `goto` ne sont exposés que lorsque le serveur est démarré avec `--gui`.
- **CLI facultative** : si MCP n'est pas votre interface préférée, `pyghidra-mcp-cli` fournit un client en ligne de commande direct via HTTP avec des commandes groupées pour les workflows courants d'édition et d'analyse.
Cela permet de garder le serveur par défaut utilisable pour les agents LLM, les intégrations IDE et l'automatisation sans exposer une surface d'outils inutile ni des contrôles réservés à la GUI dans les sessions sans interface graphique.
## Client CLI
Pour une expérience en ligne de commande plus interactive, vous pouvez utiliser le paquet séparé **pyghidra-mcp-cli**, qui fournit une interface conviviale pour interagir avec un serveur pyghidra-mcp en cours d'exécution.
### Installation
Installez le client CLI à l'aide de [`uv`](https://docs.astral.sh/uv/) (recommandé) :
```bash
uvx pyghidra-mcp-cli
```
Ou installez avec pip :
```bash
pip install pyghidra-mcp-cli
```
### Démarrage rapide avec la CLI
1. **Démarrer le serveur** (dans un terminal) :
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **Utiliser le CLI** (dans un autre 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]
> Le CLI se connecte à pyghidra-mcp via HTTP pour éviter la surcharge de démarrage de 10 à 60 secondes liée au lancement d'un nouveau processus Ghidra pour chaque commande. Consultez le [README du CLI](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) pour la documentation complète.
## Création de projets, gestion et ouverture de projets existants
### Création de nouveaux projets
Vous pouvez créer de nouveaux projets de plusieurs manières, selon votre flux de travail :
#### Structure de projet autonome
`pyghidra-mcp` crée une **structure de projet autonome** où chaque projet possède son propre projet Ghidra et ses propres artefacts pyghidra-mcp. Cela garantit une isolation complète et une gestion facile des projets.
#### Création de projet de base
```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
```
#### Création de projet personnalisé
```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
```
#### Création de plusieurs projets liés
```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
```
### Ouvrir des projets Ghidra existants
Si vous avez des projets Ghidra existants (fichiers `.gpr`), vous pouvez les ouvrir directement avec `pyghidra-mcp` :
#### Ouvrir par fichier .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)
```
### Mode GUI
Utilisez le mode GUI lorsque vous souhaitez que les actions MCP opèrent sur les mêmes objets de programme actifs que ceux affichés par Ghidra.
- `--gui` nécessite `--transport streamable-http` (ou `--transport http` comme alias)
- `--project-path` peut être un répertoire de projet plus `--project-name`, ou un fichier `.gpr` existant. Les projets manquants sont créés automatiquement.
- Ghidra est lancé par `pyghidra-mcp`, ce qui maintient les transactions GUI et MCP dans la même JVM
- Les outils réservés au mode GUI ne sont exposés que lors de l'exécution avec `--gui`
Exemple :
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
Le mode GUI est le bon choix lorsque vous souhaitez :
- ouvrir ou changer de programme dans CodeBrowser
- naviguer dans le listing vers une fonction ou une adresse
- renommer des fonctions ou ajouter des commentaires et voir immédiatement ces changements dans Ghidra
### Valeurs par défaut au démarrage et projets volumineux
`pyghidra-mcp` ne nécessite pas `--wait-for-analysis` par défaut. Le serveur peut démarrer pendant que l'analyse et l'indexation côté MCP se poursuivent en arrière-plan.
Cela compte pour les projets volumineux :
- démarrer un projet avec de nombreux binaires n'a pas besoin de bloquer le démarrage du serveur
- `--wait-for-analysis` est disponible lorsque vous voulez un projet entièrement analysé avant de servir des requêtes
- pour les projets existants volumineux, attendez-vous à ce que l'état de préparation de l'analyse et de l'indexation varie selon le binaire
Limitation actuelle :
- l'état d'analyse de Ghidra et l'état d'indexation du MCP sont distincts
- un binaire peut être entièrement analysé dans Ghidra alors que `search_strings` ou la recherche sémantique `search_code` attendent encore l'indexation côté MCP
- c'est plus visible lors de l'ouverture de projets existants plus volumineux
En pratique :
- la décompilation, la navigation, le renommage et les commentaires peuvent toujours fonctionner pour un binaire pendant que les fonctionnalités de recherche gourmandes en indexation rattrapent leur retard
- si la latence de démarrage compte plus que la disponibilité immédiate de la recherche, conservez le `--no-wait-for-analysis` par défaut
- si la disponibilité immédiate compte plus que le temps de démarrage, utilisez `--wait-for-analysis`
## Développement
Ce projet utilise un `Makefile` pour rationaliser le développement et les tests. `ruff` est utilisé pour le linting et le formatage, et les hooks `pre-commit` sont utilisés pour garantir la qualité du code.
### Configuration
1. **Installer `uv`** : Si vous n'avez pas `uv` installé, vous pouvez l'installer avec pip :
```bash
pip install uv
```
Ou, suivez le guide d'installation officiel de `uv` : [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **Créer un environnement virtuel et installer les dépendances** :
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **Définir la variable d'environnement Ghidra** : Téléchargez et installez Ghidra, puis définissez la variable d'environnement `GHIDRA_INSTALL_DIR` sur votre répertoire d'installation de 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)
```
### Tests et qualité
Le `Makefile` fournit plusieurs cibles pour les tests et la qualité du code :
- `make run` : Lancer le serveur MCP.
- `make test` : Lancer la suite de tests complète (unitaires et d'intégration).
- `make test-unit` : Lancer les tests unitaires.
- `make test-integration` : Lancer les tests d'intégration.
- `make test-integration-fast` : Lancer le test de fumée d'intégration léger utilisé par pre-commit.
- `make test-integration-gui` : Lancer les tests d'intégration GUI. Nécessite une installation Ghidra fonctionnelle et un support GUI.
- `make lint` : Vérifier le style de code avec `ruff`.
- `make format` : Formater le code avec `ruff`.
- `make typecheck` : Lancer des vérifications statiques légères avec `ruff`.
- `make check` : Lancer toutes les vérifications de qualité.
- `make dev` : Lancer le flux de travail de développement (formatage et vérification).
- `make build` : Construire les paquets de distribution.
- `make clean` : Nettoyer les artefacts de build et le cache.
Répartition recommandée :
- pre-commit : `ruff`, `pyright`, tests unitaires, et un test de fumée d'intégration léger
- GitHub Actions : couverture complète d'intégration Linux headless, GUI Linux sous `Xvfb`, couverture CLI, et tests de fumée macOS actuels
- CI planifiée : couverture de compatibilité macOS / Ghidra plus anciens
- local/manuel : débogage GUI plus lourd spécifique à l'environnement et vérifications de sanity pour les releases
## API
### Outils
Permettre aux LLM d'effectuer des actions, d'effectuer des calculs déterministes et d'interagir avec des services externes.
#### Opérations par lots
`decompile_function` et `list_xrefs` acceptent une cible unique ou une liste de cibles, réduisant les allers-retours lors de l'analyse de chaînes d'appels ou de plusieurs symboles à la fois.
```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"]
}
```
Les erreurs par élément sont renvoyées en ligne (les autres cibles réussissent quand même) :
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### Outils de lecture / analyse
- `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)` : Recherche dans le pseudo-C décompilé à l'aide d'une recherche vectorielle sémantique ou d'une correspondance littérale.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])` : Liste les références croisées vers une ou plusieurs fonctions, un ou plusieurs symboles, ou une ou plusieurs adresses. Accepte une cible unique ou une liste pour une recherche par lots.
- `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)` : Génère un graphe d'appels MermaidJS pour une fonction spécifiée. Prend en charge les directions "calling" (fonctions appelées par la cible) et "called" (fonctions qui appellent la cible) avec plusieurs types de visualisation.
- `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)` : Décompile une ou plusieurs fonctions par nom ou adresse. Accepte une cible unique ou une liste pour une décompilation par lots. Les indicateurs de réponse enrichie attachent les appelés, les chaînes et/ou les xrefs à chaque résultat. `timeout_sec` s'applique par cible et limite chaque tentative de décompilation indépendamment.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)` : Liste toutes les fonctions et symboles exportés d'un binaire spécifié (regex prise en charge pour la requête).
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)` : Liste toutes les fonctions et symboles importés d'un binaire spécifié (regex prise en charge pour la requête).
- `read_bytes(binary_name: str, address: str, size: int = 32)` : Lit les octets bruts en mémoire à une adresse spécifiée. Les adresses hexadécimales peuvent inclure ou omettre le préfixe `0x`.
- `search_strings(binary_name: str, query: str, limit: int = 100)` : Recherche des chaînes dans un binaire.
- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)` : Recherche des symboles dans un binaire par nom. Prend en charge les motifs regex (par ex. `^main$`, `func.*one`) avec correspondance insensible à la casse, ou des requêtes de sous-chaîne simples. Définissez `functions_only=True` pour exclure les labels, les variables et autres symboles non-fonctionnels.
#### Opérations sur le projet
- `import_binary(binary_path: str)` : Importe un binaire depuis un chemin désigné dans le projet Ghidra courant. Si le chemin est un répertoire, il analysera et importera récursivement tous les fichiers binaires pris en charge, en préservant la structure du répertoire au sein du projet Ghidra.
- `list_project_binaries()` : Liste les binaires du projet Ghidra courant. En mode GUI, cela inclut les binaires du projet qui existent sur le disque même s'ils ne sont pas actuellement ouverts dans CodeBrowser.
- `list_project_binary_metadata(binary_name: str)` : Récupère les métadonnées détaillées d'un binaire spécifique, notamment l'architecture, le compilateur, le format exécutable, les métriques d'analyse et les hachages de fichiers.
- `delete_project_binary(binary_name: str)` : Supprime un binaire (programme) du projet Ghidra.
#### Outils d'édition / mutation
- `rename_function(binary_name: str, name_or_address: str, new_name: str)` : Renomme une fonction par nom ou adresse. En mode GUI, cela s'exécute comme une transaction Ghidra en direct et met à jour le programme ouvert.
- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)` : Renomme un paramètre de fonction ou une variable locale par nom exact au sein d'une fonction spécifique. Si le nom est manquant ou ambigu dans cette fonction, l'outil renvoie une erreur au lieu de deviner. En mode GUI, cela s'exécute comme une transaction Ghidra en direct et met à jour le programme ouvert.
- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)` : Définit le type de données d'un paramètre de fonction ou d'une variable locale par nom exact au sein d'une fonction spécifique. Si le nom est manquant ou ambigu dans cette fonction, l'outil renvoie une erreur au lieu de deviner. `type_name` est analysé à l'aide de l'analyseur de types de données de Ghidra par rapport au gestionnaire de types de données du programme.
- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)` : Définit un prototype de fonction à partir d'une chaîne de signature complète. L'outil fait toujours passer le prototype par l'analyseur de signatures natif de Ghidra et renvoie l'erreur d'analyse ou d'application sous-jacente si le prototype est invalide.
- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)` : Définit un commentaire de fonction/décompilateur ou un commentaire de listing. Les cibles de commentaire de listing peuvent être des adresses, des symboles ou des fonctions. Les valeurs prises en charge pour `comment_type` sont `decompiler`, `plate`, `pre`, `eol`, `post` et `repeatable`.
#### Outils de contrôle de l'interface graphique (`--gui` uniquement)
Ces outils ne sont disponibles que lorsque `pyghidra-mcp` est démarré avec `--gui` et contrôlent ce que l'interface graphique affiche plutôt que de modifier directement les données du projet :
- `list_open_programs()` : Liste les programmes actuellement ouverts dans l'interface graphique de Ghidra.
- `open_program_in_gui(binary_name: str, new_window: bool = True)` : Ouvre un binaire du projet dans CodeBrowser. Par défaut, cela ouvre une nouvelle fenêtre CodeBrowser. Définissez `new_window=false` pour réutiliser un CodeBrowser visible lorsque c'est possible.
- `set_current_program(binary_name: str)` : Fait d'un programme ouvert le programme actif/courant dans le contexte principal de l'outil GUI.
- `goto(binary_name: str, target: str, target_type: str)` : Navigue dans l'interface graphique de Ghidra vers une adresse ou une fonction. `target_type` doit être `address` ou `function`.
## Utilisation
Ce paquet Python est publié sur PyPI sous le nom [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) et peut être installé et exécuté avec [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/), ou tout gestionnaire de paquets 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.
```
### Mapper des binaires avec Docker
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)