Ghidra MCP Server

Si vous trouvez cela utile, n'hésitez pas à ⭐ ajouter une étoile au dépôt — cela aide d'autres à le découvrir !

Si Ghidra MCP vous fait gagner du temps, envisagez de soutenir le projet. Les soutiens ponctuels et récurrents aident tous deux à financer les mises à jour de compatibilité, le durcissement de la production, la documentation et les nouveaux outils.

Un serveur Model Context Protocol (MCP) prêt pour la production qui relie les puissantes capacités de rétro-ingénierie de Ghidra aux outils d'IA modernes et aux frameworks d'automatisation. 271 outils MCP, des workflows d'IA éprouvés et l'intégration Ghidra-MCP la plus complète disponible — incluant désormais l'émulation P-code, l'intégration du débogueur en direct et l'analyse de flux de données via les graphes PCode.

Pourquoi Ghidra MCP ?

La plupart des implémentations Ghidra MCP vous offrent une poignée d'outils en lecture seule et s'arrêtent là. Ce projet est différent — il a été construit par un ingénieur en rétro-ingénierie qui l'utilise quotidiennement sur des binaires réels, pas comme une démonstration.

• 271 outils MCP — 3 fois plus que toute autre implémentation concurrente. Pas seulement des opérations de lecture — un accès complet en écriture pour renommer, typer, commenter, créer des structures, exécuter des scripts, l'émulation P-code et le débogage en direct.
• Workflows d'IA éprouvés — Des workflows de documentation éprouvés (V5) peaufinés sur des centaines de fonctions. Inclut des invites pas à pas, une référence de notation hongroise, des guides de traitement par lots et une découverte de code orphelin.
• Fiabilité de qualité production — Transactions atomiques, opérations par lots (réduction de 93 % des appels API), délais d'attente configurables et gestion gracieuse des erreurs. Pas d'échecs silencieux.
• Transfert de documentation entre binaires — Le hachage SHA-256 des fonctions propage automatiquement la documentation entre les versions de binaires. Documentez une fois, appliquez partout.
• Intégration complète du serveur Ghidra — Connectez-vous à des serveurs Ghidra partagés, gérez des dépôts, le contrôle de version, les workflows d'extraction/validation et la collaboration multi-utilisateurs.
• Modes sans tête et avec interface graphique — Fonctionne avec ou sans l'interface graphique Ghidra. Prêt pour Docker pour les pipelines CI/CD et l'analyse automatisée à grande échelle.
• Conçu par opinion — La version 5.0 déplace les conventions de nommage, la sécurité des types et les normes de documentation dans la couche d'outils. Les agents IA et les ingénieurs humains produisent des résultats cohérents sans guides de style dans chaque invite.

Application des conventions

Vous êtes déjà passé par là : six mois dans un projet vous trouvez ProcessItem, process_items, handleItem et ItemProc dans la même base de code — quatre fonctions faisant la même chose, nommées par quatre sessions ou ingénieurs différents sans contrat partagé. Les corriger prend plus de temps que nécessaire, et le problème se reproduira.

La version 5.0 déplace les conventions de « choses à retenir » dans la couche d'outils, où elles peuvent réellement être appliquées.

Pour les agents IA, cela signifie des résultats cohérents à chaque session, chaque modèle, chaque exécution — sans coller un guide de style dans chaque invite. L'outil connaît les règles ; le modèle n'a qu'à prendre la décision.

Pour les équipes, cela élimine toute la classe de commentaires de revue qui disent « ce n'est pas notre convention de nommage ». L'arbitrage des conventions reste dans l'outil, pas dans la revue de code.

Pour le travail solo à grande échelle, analyze_function_completeness vous donne un score de 0 à 100 % qui mesure honnêtement : les déductions structurelles (artefacts de compilateur non réparables) sont pardonnées dans votre score effectif, la mise à l'échelle logarithmique empêche une mauvaise catégorie de tout enterrer, et la qualité commentée par niveaux vous indique exactement ce qui manque et pourquoi.

🌟 Fonctionnalités

Intégration MCP principale

• Compatibilité MCP complète — Implémentation complète du Model Context Protocol
• 271 outils MCP — Surface API complète couvrant tous les aspects de l'analyse binaire
• Fiabilité prête pour la production — Transactions atomiques, opérations par lots, délais d'attente configurables
• Analyse en temps réel — Intégration en direct avec le moteur d'analyse de Ghidra

Note de compatibilité : Les noms des outils MCP sont normalisés pour GitHub Copilot CLI et la validation CAPI. Les noms d'outils exposés utilisent uniquement des lettres minuscules, des chiffres, des tirets bas et des traits d'union ; les chemins HTTP imbriqués tels que /debugger/status sont annoncés sous des noms comme debugger_status_2 si nécessaire pour éviter les collisions avec les outils de pont statiques.

Capacités d'analyse binaire

• Analyse de fonctions — Décompilation, graphes d'appels, références croisées, score de complétude
• Analyse de flux de données — Propagation de valeurs via graphe PCode (avant / arrière) depuis n'importe quelle variable ou registre
• Découverte de structures de données — Création de structures/union/énumérations avec analyse de champs et suggestions de nommage
• Extraction de chaînes — Recherche par regex, filtrage par qualité, découverte de fonctions ancrées sur des chaînes
• Analyse import/export — Tables de symboles, emplacements externes, résolution d'imports par ordinal
• Inspection de la mémoire et des données — Lectures mémoire brutes, recherche de motifs d'octets, détection de limites de tableaux
• Documentation entre binaires — Appariement par hachage de fonctions et propagation de la documentation entre versions

Analyse dynamique (v5.4.0)

• Émulation P-code — Exécutez n'importe quelle fonction de manière isolée via EmulatorHelper de Ghidra ; résolvez par force brute les hachages d'API en quelques millisecondes
• Intégration du débogueur en direct — 17 points d'extrémité Java + 22 outils de pont Python via le framework TraceRmi de Ghidra (dbgeng sur Windows PE, gdb/lldb sinon) : attachement, pas à pas, points d'arrêt, registres, lectures mémoire, traçage de fonctions sans interruption, traduction d'adresses statique↔dynamique en tenant compte de l'ASLR

Workflows de rétro-ingénierie assistés par IA

• Workflow de documentation de fonctions V5 — Processus en 7 étapes pour une documentation complète des fonctions avec notation hongroise, audit des types et notation de vérification automatisée
• Documentation par lots — Distribution parallèle de sous-agents pour documenter plusieurs fonctions simultanément
• Découverte de code orphelin — Scanner automatisé qui trouve les fonctions non découvertes dans les lacunes entre le code connu
• Investigation des types de données — Workflows systématiques pour la découverte de structures et l'analyse de champs
• Appariement entre versions — Correspondance par hachage des fonctions entre différentes versions de binaires

Développement et automatisation

• Gestion des scripts Ghidra — Créer, exécuter, mettre à jour et supprimer des scripts Ghidra entièrement via MCP
• Support multi-programmes — Basculer entre et comparer plusieurs programmes ouverts
• Opérations par lots — Renommage, commentaires, types et gestion d'étiquettes en masse (93 % d'appels API en moins)
• Serveur sans tête — Analyse complète sans interface graphique Ghidra — prêt pour Docker et CI/CD
• Gestion de projet et contrôle de version — Créer des projets, gérer des fichiers, intégration du serveur Ghidra
• Contrôle de l'analyse — Lister, configurer et déclencher les analyseurs Ghidra de manière programmatique

🚀 Démarrage rapide

Prérequis

• Java 21 LTS (OpenJDK recommandé)
• Apache Maven 3.9+
• Ghidra 12.1.2 (ou version compatible)
• Python 3.10+ avec uv (recommandé) ou pip + venv

Utilisateurs de serveur Ghidra partagé : les clients Ghidra 12.1.2 nécessitent un serveur Ghidra en version 12.1, 12.0.5 ou une version compatible plus récente. Mettez à niveau le serveur avant d'utiliser ce plugin depuis un client 12.1.

Ghidra 12.1.2 inclut Jython en tant qu'extension optionnelle. Les scripts Java fonctionnent par défaut, mais les scripts .py dans ghidra_scripts/ nécessitent d'installer l'extension Jython depuis Fichier > Installer les extensions et de redémarrer Ghidra.

Installation

Recommandé pour toutes les plateformes : utilisez python -m tools.setup directement.

ensure-prereqs installe les dépendances Python d'exécution ainsi que les JARs Ghidra nécessaires dans le dépôt Maven local. deploy copie la sortie de compilation, installe l'extension du profil utilisateur et patche la configuration utilisateur de Ghidra.

1. Clonez le dépôt : ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Recommandé: exécutez d'abord le précontrôle de l'environnement: ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. Construire et déployer vers Ghidra: ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy sauvegarde/ferme une instance Ghidra correspondante déjà en cours d'exécution lorsque nécessaire, installe l'extension, lance Ghidra, attend la disponibilité du MCP, et exécute des tests de vérification de schéma.

4. Mode strict/manuel optionnel (avancé) : ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. Afficher l'aide de la commande: ```text python -m tools.setup --help
   root@kitploit:~

6. Mode de construction uniquement optionnel (avancé/dépannage) : ```text python -m tools.setup build
   root@kitploit:~

Chemin de build pris en charge : python -m tools.setup build utilise Maven sous le capot et est le workflow canonique utilisé par les tâches et la documentation du dépôt. ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

- [Stunner](https://github.com/firefart/stunner) - Outil pour tester et exploiter les serveurs STUN, TURN et TURN over TCP. TURN est un protocole principalement utilisé dans les vidéoconférences et les discussions audio (WebRTC).   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

Installation (Linux — Ubuntu/Debian)

1. Clonez le dépôt : ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Installer les prérequis système (s'ils ne sont pas déjà installés): ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

Note Debian/Kali/Ubuntu 23.04+ (PEP 668) : ces distributions marquent le Python système comme géré en externe, donc un simple pip install échoue avec error: externally-managed-environment. Ne le contournez pas avec --break-system-packages — cela pourrait corrompre les outils gérés par apt. Utilisez plutôt uv (recommandé — il crée et gère automatiquement un .venv local au projet, et c'est ce qu'utilisent les commandes de ce dépôt) :

root@kitploit:~

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # résout les dépendances dans .venv et démarre le pont

ou un environnement virtuel classique :

root@kitploit:~

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra
```   ```bash

python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC

4. **Construire et déployer dans Ghidra (commande unique) :**   ```bash
python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC
python -m tools.setup build
python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC

Cela va :

• Installer les dépendances JAR de Ghidra dans votre ~/.m2/repository local
• Construire GhidraMCP-<version>.zip avec Maven
• Extraire l'extension vers ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/
• Mettre à jour preferences avec LastExtensionImportDirectory
• Installer les dépendances Python

5. Optionnel : configurer uniquement les dépendances Maven : ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. Afficher l'aide de la commande : ```bash python -m tools.setup --help
   root@kitploit:~

Chemins Linux : L'extension est installée dans $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/. Les fichiers de configuration de Ghidra se trouvent dans $HOME/.config/ghidra/ghidra_<version>_PUBLIC/.

Installation (macOS — Homebrew)

1. Installer les prérequis : ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. Cloner le dépôt: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. Installer les JARs Ghidra dans le Maven local : ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. Construire et déployer: ```bash python -m tools.setup ensure-prereqs
   --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

L'extension est installée dans ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.

Remarque : --ghidra-version est requis lors de l'utilisation du chemin Homebrew car le chemin ne contient pas de chaîne de version.

5. Démarrer Ghidra et activer le plugin : ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

Dans la fenêtre principale du projet : Tools > GhidraMCP > Start MCP Server

6. Configurer Cursor/Claude MCP (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

Installation (Arch Linux — AUR)

@Pandoriaantje maintient les paquets AUR de la communauté :

• ghidra-mcp-git — suit main
• ghidra-mcp — suit les versions étiquetées

Installez avec l'assistant AUR de votre choix, par ex. :```bash yay -S ghidra-mcp # or ghidra-mcp-git

### Utilisation de base

#### Option 1 : Transport Stdio (Recommandé pour les outils d'IA)```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

Pour ajouter le pont vers Autohand Code depuis un checkout cloné:```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Add `--scope project` avant `ghidra` pour enregistrer le serveur dans la configuration `.autohand` du projet actuel au lieu de votre configuration utilisateur.

#### Option 2 : Transport HTTP streamable (Recommandé pour les clients web/HTTP)```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

Configuration du client MCP pour le transport HTTP (ajouter au fichier de configuration MCP de votre client) :```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

Clients basés sur un navigateur (par exemple [MCP Inspector](https://github.com/modelcontextprotocol/inspector))
fonctionnent immédiatement : les transports HTTP répondent aux requêtes préparatoires CORS (`OPTIONS`) et exposent
les en-têtes `mcp-session-id` / `mcp-protocol-version` aux scripts. Les origines autorisées reflètent la
politique d'en-tête Host — le loopback sur n'importe quel port est toujours autorisé, ainsi que l'hôte de liaison et tous les
hôtes listés dans `GHIDRA_MCP_ALLOWED_HOSTS`.

#### Option 3 : Transport SSE (Obsolète — utilisez streamable-http à la place)```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

Drapeaux avancés du pont

Routage strict des programmes (sécurité multi-programme)

Définissez GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 pour que le pont refuse tout appel au niveau du programme qui omet un sélecteur de programme, renvoyant une erreur claire au lieu de laisser l'appel utiliser le « programme actuel » partagé du serveur (celui que switch_program et l'onglet GUI actif déplacent).```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

Sans cela, un appel qui omet `program=` s'exécute sur le programme en cours, ce qui est acceptable pour un flux de travail à programme unique mais devient un risque dès que plusieurs programmes sont ouverts : l'appel peut lire ou modifier le mauvais binaire sans erreur. Le risque est plus grave lorsque plusieurs clients partagent un serveur, car chacun déplace cette variable globale du programme en cours au détriment des autres.

Avec le mode strict activé, chaque appel limité à un programme doit nommer sa cible. Cela couvre tous les sélecteurs qui choisissent un programme ouvert : le simple `program=` et les `source_program`/`target_program` ou `program_a`/`program_b` des outils inter-programmes (déclarés obligatoires, mais le serveur revient toujours au programme en cours lorsque l'un d'eux arrive vide). Un sélecteur oublié se manifeste par une erreur bruyante dès le premier mauvais appel au lieu d'une écriture silencieuse sur le mauvais binaire. Les outils sans sélecteur de programme (`open_program` et `close_program` prennent `path`/`name`) ne sont pas affectés. Désactivé par défaut : avec la variable non définie, le pont envoie les appels inchangés.

#### Réduire la surcharge du contexte des outils

Le pont expose un catalogue vaste. Pour garder la surface d'outils du modèle petite, exécutez avec `--lazy` (charge uniquement `listing,function,program` lors de la connexion) et laissez le modèle **découvrir** le reste à la demande plutôt que de tout enregistrer :

- `search_tools("rename function")` — recherche par mot-clé dans **l'ensemble** du catalogue, y compris les outils dont le groupe n'est pas chargé. Chaque résultat indique s'il est appelable maintenant et, sinon, l'appel exact `load_tool_group(...)` pour l'activer.
- `list_tool_groups()` — liste toutes les catégories et leur état de chargement.
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — charger ou supprimer une catégorie à l'exécution.
- `check_tools("rename_or_label,batch_set_comments")` — confirmer que les outils spécifiques sont appelables à l'instant.

`search_tools` fonctionne en mode eager et en mode `--lazy`, de sorte que les agents qui respectent `tools/list_changed` bénéficient d'une découverte complète sans le coût initial du contexte.

#### Optionnel : Démarrer le serveur de débogage autonome```bash
uv sync --group debugger
uv run python -m debugger

Le serveur de débogage écoute sur http://127.0.0.1:8099/ par défaut et est requis pour les outils proxy debugger_* exposés par le pont MCP.

Indicateurs du serveur de débogage :

Définissez GHIDRA_DEBUGGER_URL dans .env si vous modifiez le port ou l'hôte par défaut pour que le pont puisse le trouver.

Dans Ghidra

1. Lancez Ghidra et ouvrez une fenêtre CodeBrowser
2. Dans CodeBrowser, activez le plugin via File > Configure > Configure All Plugins > GhidraMCP
3. Optionnel : configurez un port personnalisé via CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server
4. Démarrez le serveur via Tools > GhidraMCP > Start MCP Server
5. Le serveur tourne sur http://127.0.0.1:8089/ par défaut

Vérifiez que ça fonctionne```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## Soutenir ce projet

Si Ghidra MCP vous fait gagner du temps en ingénierie ou en rétro‑ingénierie, envisagez de [soutenir le projet](https://github.com/sponsors/bethington).

- Un soutien ponctuel aide à financer les correctifs, les mises à jour de compatibilité et le travail de publication.
- Un soutien récurrent permet de maintenir la maintenance, la documentation et le renforcement en production.
- Le soutien d’entreprise aide à prioriser la fiabilité à long terme pour le pont, le serveur headless, l’intégration du débogueur et les outils de workflow.

## 🔒 Sécurité

GhidraMCP est conçu pour un **développement local uniquement**. La configuration par défaut — serveur HTTP lié à `127.0.0.1`, sans authentification — est sûre sur un poste de travail fiable mono‑utilisateur et correspond au comportement antérieur à la v5.4.1.

**Si vous exposez le serveur au‑delà du loopback, configurez d’abord ces trois variables d’environnement.** Le serveur refuse de démarrer sur une liaison non‑loopback sans jeton.

| Variable d’env | Effet |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | Lorsqu’elle est définie, chaque requête HTTP doit porter `Authorization: Bearer <token>`. Comparaison sécurisée contre les attaques temporelles. `/mcp/health`, `/health`, `/check_connection` sont exemptées. |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | Définissez sur `1`, `true` ou `yes` pour activer `/run_script_inline` et `/run_ghidra_script`. **Désactivé par défaut depuis la v5.4.1** — ces points de terminaison exécutent du Java arbitraire sur le processus Ghidra. En mode headless, cela déclenche également l’initialisation OSGi `BundleHost` au démarrage du serveur (framework Felix, ~centaines de ms) ; laissez‑le désactivé si vous n’avez pas besoin d’exécution de scripts. |
| `GHIDRA_MCP_FILE_ROOT` | Lorsqu’elle est définie sur un chemin de répertoire, les points de terminaison de chemin de fichiers (`/load_program`, `/import_file`, `/open_project`, `/delete_file`, etc.) canonicisent l’entrée et exigent qu’elle se trouve sous cette racine. Empêche le path‑traversal. |

Le contrôle de la qualité des noms est distinct de la sécurité. Par défaut, `rename_function_by_address` et les points de terminaison d’écriture globale rejettent les noms qui échouent aux contrôles de qualité intégrés, et les écritures de champs de structure appliquent la convention de préfixe de champ intégrée. Désactivez la couche de convention intégrée avec **Edit > Tool Options > GhidraMCP HTTP Server > Strict Naming Enforcement**. La même case à cocher des Tool Options couvre `rename_data`, `rename_global_variable`, `set_global`, la garde de préfixe/type `apply_data_type`, et les corrections automatiques de préfixe hongrois pour les champs de structure dans `create_struct`, `add_struct_field` et `modify_struct_field`. Le paramètre est lu au démarrage ou au redémarrage du serveur MCP. Les avertissements de convention pour les fonctions/globales sont toujours renvoyés lorsque le contrôle est désactivé.

### Exemple : exposition à un LAN privé avec authentification```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

Authentification du serveur Ghidra

Lors de la connexion à un serveur Ghidra partagé, GhidraMCP peut supprimer automatiquement la boîte de dialogue de mot de passe. Il résout les identifiants dans cet ordre (la première valeur non vide l'emporte) :

Note de compatibilité : les clients Ghidra 12.1.2 nécessitent un serveur Ghidra 12.1.2, 12.0.5 ou un serveur compatible plus récent. Les anciens serveurs partagés ne sont pas des cibles sûres pour une mise à niveau du client 12.1.

1. GHIDRA_SERVER_PASSWORD variable d'environnement (ou fichier .env dans le répertoire d'installation de Ghidra ou ~)
2. ~/.ghidra-cred — fichier de mot de passe sur une seule ligne dans votre répertoire personnel
3. <ghidra-install-dir>/.ghidra-cred

Le nom d'utilisateur est résolu de la même manière : variable d'environnement GHIDRA_SERVER_USER → propriété système user.name.

Si aucun mot de passe n'est trouvé, Ghidra affiche son invite GUI normale. Définissez-les dans .env (voir .env.template pour le bloc complet) pour activer l'authentification silencieuse.

Migration de v5.4.0 → v5.4.1

• Les points de terminaison de script sont désormais désactivés par défaut. Si vous comptiez sur /run_script_inline ou /run_ghidra_script, exportez GHIDRA_MCP_ALLOW_SCRIPTS=1. Il s'agit d'un changement délibérément cassant ; la valeur par défaut précédente n'était pas sûre.
• Les déploiements en localhost uniquement ne nécessitent aucune modification. L'authentification, le refus de liaison et les vérifications de racine de chemin sont tous facultatifs.

❓ Dépannage

Le menu "GhidraMCP" n'apparaît pas dans Outils

Cause : Plugin non activé ou installé incorrectement.

Solution :

1. Vérifiez que l'extension est installée : Fichier > Installer les extensions — GhidraMCP doit être listé
2. Activez le plugin : Fichier > Configurer > Configurer tous les plugins > GhidraMCP (cochez la case)
3. Redémarrez Ghidra après l'installation/l'activation

Le serveur ne répond pas / Connexion refusée

Cause : Serveur non démarré ou mauvais port.

Solution :

1. Assurez-vous d'avoir démarré le serveur : Outils > GhidraMCP > Démarrer le serveur MCP
2. Vérifiez le port configuré : Édition > Options des outils > Serveur HTTP GhidraMCP
3. Vérifiez si le port est utilisé : ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. Recherchez les erreurs dans la console Ghidra : Window > Console

pip install échoue avec error: externally-managed-environment

Cause : PEP 668. Les distributions de la famille Debian (Debian 12+, Kali, Ubuntu 23.04+) marquent le Python système comme géré de manière externe, donc l'installation globale via pip install est bloquée pour protéger les paquets gérés par apt.

Solution : Utilisez un environnement virtuel — jamais --break-system-packages. Le chemin recommandé est uv, qui gère automatiquement un .venv local au projet :```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

Ou un venv classique:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger échoue avec ModuleNotFoundError pour pybag ou comtypes

Cause: Le serveur de débogage autonome utilise des dépendances Python optionnelles uniquement pour Windows qui ne sont pas installées par défaut.

Solution:```text uv sync --group debugger uv run python -m debugger

Si vous avez à la fois un Python global et un venv de projet, assurez-vous d’installer et d’exécuter à partir du même interpréteur.

### Erreurs 500 – Erreur interne du serveur

**Cause:** Exception côté serveur, souvent due à des données de programme manquantes.

**Solution:**
1. Assurez-vous qu'un binaire est chargé dans CodeBrowser
2. Lancez d'abord l'analyse automatique : **Analysis > Auto Analyze**
3. Vérifiez la console Ghidra (**Window > Console**) pour les exceptions Java
4. Certaines opérations nécessitent des binaires entièrement analysés

### Erreurs 404 – Non trouvé

**Cause:** Le point d'accès n'existe pas ou URL incorrecte.

**Solution:**
1. Vérifiez que le point d'accès existe : `curl http://127.0.0.1:8089/get_version`
2. Vérifiez les fautes de frappe dans le nom du point d'accès
3. Assurez-vous d'utiliser la méthode HTTP correcte (GET vs POST)

### Les scripts Python Ghidra échouent avec « No script provider found »

**Cause:** Dans Ghidra 12.1.2, le support Jython n'est plus activé par défaut. Les scripts `.py` ont besoin de l'extension Jython fournie ; les scripts Python 3 doivent utiliser PyGhidra au lieu du Gestionnaire de scripts Ghidra.

**Solution:**
1. Dans l'interface Ghidra, ouvrez **File > Install Extensions**.
2. Cochez **Jython**, redémarrez Ghidra, puis actualisez le Gestionnaire de scripts.
3. Pour les nouvelles automatisations, préférez les scripts Java Ghidra ou PyGhidra.

### L'extension n'apparaît pas dans Install Extensions

**Cause:** Le fichier JAR est au mauvais endroit.

**Solution:**
1. Emplacement d'installation manuelle : `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. Ou utilisez : **File > Install Extensions > Add** et sélectionnez le fichier ZIP
3. Assurez-vous que le JAR/ZIP a été construit pour votre version de Ghidra

### La construction échoue avec « Ghidra dependencies not found »

**Cause:** Les JARs Ghidra ne sont pas installés dans le dépôt Maven local.

**Solution:**```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 Performances de production

• Outils MCP : 271 outils entièrement implémentés
• Vitesse : Réponse inférieure à la seconde pour la plupart des opérations
• Efficacité : 93% de réduction des appels API grâce aux opérations par lots
• Fiabilité : Transactions atomiques avec sémantique tout-ou-rien
• Flux de travail IA : Invites de documentation éprouvées et affinées sur des centaines de fonctions réelles
• Déploiement : Script de déploiement automatisé conscient de la version

🛠️ Référence API

271 outils MCP soutenus par des points de terminaison HTTP, regroupés par catégorie de catalogue. Généré à partir de tests/endpoints.json par python -m tools.gen_readme_api_reference --write ; le schéma en direct à /mcp/schema fait autorité à l'exécution. Modèles d'utilisation : docs/prompts/TOOL_USAGE_GUIDE.md.

Gestion des programmes et des sessions

• analysis_status - Obtenir l'état d'analyse automatique pour les programmes ouverts
• close_program - Fermer un programme ouvert par chemin de projet ou nom
• create_property_map - Créer un mappage de propriétés utilisateur pour stocker des valeurs typées indexées par adresse
• delete_property_map - Supprimer un mappage de propriétés utilisateur et toutes ses valeurs
• exit_ghidra - Sauvegarder et quitter Ghidra
• get_address_spaces - Lister tous les espaces d'adressage physiques et de superposition dans le programme (les superpositions incluent le drapeau is_overlay et le nom overlayed_space)
• get_current_program_info - Obtenir les informations du programme actuel
• get_language_metadata - Dump la description du langage du programme : espaces d'adressage, registres, symboles par défaut, endianness, taille des pointeurs (issue #192)
• get_program_options - Lire toutes les options d'un groupe d'options du programme avec leurs types, valeurs actuelles, valeurs par défaut et descriptions
• get_property - Lire la valeur stockée à une adresse dans un mappage de propriétés
• import_file - Importer un fichier binaire du disque dans le projet Ghidra actuel et l'ouvrir
• list_open_programs - Lister les programmes ouverts
• list_option_groups - Lister les groupes d'options du programme (par ex.
• list_project_files - Lister les fichiers du projet
• list_properties - Lister les entrées (adresse, valeur) stockées dans un mappage de propriétés, avec pagination
• list_property_maps - Lister les mappages de propriétés utilisateur — des magasins clé→valeur typés par adresse
• open_program - Ouvrir un programme depuis le projet
• reanalyze - Déclencher une analyse automatique complète sur un programme
• remove_program_option - Supprimer une option d'un groupe d'options du programme
• remove_property - Supprimer la valeur stockée à une seule adresse dans un mappage de propriétés
• save_all_programs - Sauvegarder tous les programmes ouverts
• save_program - Sauvegarder le programme actuel
• set_image_base - Définir l'adresse de base du programme (rebase toutes les adresses)
• set_program_option - Définir une option de programme typée
• set_property - Définir une valeur à une adresse dans un mappage de propriétés
• switch_program - Changer de programme actuel

Organisation du projet

• create_folder - Créer un dossier dans le projet
• delete_file - Supprimer un fichier du projet
• delete_project - Supprimer un projet Ghidra
• list_projects - Lister les projets Ghidra disponibles
• move_file - Déplacer un fichier vers un autre dossier du projet
• move_folder - Déplacer un dossier vers un autre emplacement
• project_info - Obtenir des informations détaillées sur le projet, y compris les outils en cours d'exécution et les programmes ouverts

Projet sans tête et cycle de vie du programme

Disponible sur le serveur sans tête autonome (GhidraMCPHeadlessServer).

• archive_project - Archiver le projet actuellement ouvert dans un fichier .gar natif de Ghidra
• checkin_program - Réintégrer un programme ouvert dans le serveur Ghidra partagé en tant que nouvelle version
• close_project - Fermer le projet actuellement ouvert
• create_project - Créer un nouveau projet Ghidra
• export_program - Exporter un programme ouvert ou résidant dans le projet vers un fichier zip Ghidra (.gzf)
• get_project_info - Obtenir des informations sur le projet actuellement ouvert
• import_program - Importer un fichier zip Ghidra (.gzf) dans le projet actuellement ouvert en tant que nouveau DomainFile sous target_folder (par défaut '/')
• load_program - Charger un fichier binaire dans le serveur sans tête pour analyse
• load_program_from_project - Charger un programme depuis un projet Ghidra (sans tête)
• open_project - Ouvrir un projet Ghidra existant (fichier .gpr ou répertoire)
• restore_project - Restaurer une archive Ghidra .gar dans un nouveau projet sur disque dans parent_dir/project_name
• server_status - Vérifier l'état de la connexion au serveur sans tête

Liste et énumération

• list_bookmarks - Lister les marque-pages
• list_calling_conventions - Lister les conventions d'appel disponibles
• list_classes - Lister les noms d'espaces de noms/classes
• list_data_items - Lister les données définies
• list_data_items_by_xrefs - Lister les données triées par nombre de références croisées
• list_exports - Lister les symboles exportés
• list_external_locations - Lister les emplacements externes
• list_functions - Lister les fonctions avec adresses
• list_functions_enhanced - Lister les fonctions avec métadonnées
• list_globals - Lister les variables globales
• list_imports - Lister les symboles importés
• list_methods - Lister tous les noms de fonctions avec pagination
• list_namespaces - Lister tous les espaces de noms
• list_scripts - Lister les scripts Ghidra disponibles
• list_segments - Lister les segments mémoire
• list_strings - Lister les chaînes définies

Contexte et recherches

• get_current_address - Obtenir l'adresse du curseur (interface graphique uniquement)
• get_current_function - Obtenir la fonction au curseur (interface graphique uniquement)
• get_current_selection - Obtenir les plages d'adresses surlignées dans le listing CodeBrowser (interface graphique uniquement)
• get_entry_points - Obtenir les points d'entrée du programme
• get_enum_values - Obtenir les valeurs d'énumération
• get_external_location - Obtenir les détails d'un emplacement externe
• get_full_call_graph - Obtenir le graphe d'appel complet
• get_function_by_address - Obtenir la fonction à une adresse
• get_function_call_graph - Obtenir le graphe d'appel
• get_function_callees - Obtenir les fonctions appelées
• get_function_callers - Obtenir les fonctions appelantes
• get_function_count - Retourner le nombre de fonctions dans le programme chargé
• get_function_jump_targets - Obtenir les cibles de saut
• get_function_labels - Obtenir les étiquettes dans une fonction
• get_function_variables - Lister toutes les variables dans une fonction
• get_struct_layout - Obtenir la disposition d'une structure
• get_valid_data_types - Obtenir les noms de types de données valides

Recherche

• find_similar_functions - Trouver des fonctions similaires
• search_byte_patterns - Rechercher des motifs d'octets
• search_data_types - Rechercher des types de données
• search_functions - Rechercher des fonctions par nom
• search_functions_enhanced - Recherche avancée de fonctions
• search_strings - Rechercher des chaînes définies par un motif expression régulière/sous-chaîne

Décompilation et désassemblage

• decompile_function - Décompiler une fonction
• disassemble_bytes - Désassembler une plage d'octets
• disassemble_function - Désassembler une fonction
• force_decompile - Forcer une nouvelle décompilation

Étiquettes, variables et attributs de fonction

• add_function_tag - Attacher une ou plusieurs étiquettes à une fonction
• batch_add_function_tags - Attacher des étiquettes à plusieurs fonctions en une transaction
• batch_remove_function_tags - Détacher des étiquettes de plusieurs fonctions en une transaction
• clear_flow_and_repair - Exécuter l'action GUI 'Clear Flow and Repair' de Ghidra sur une plage de départ : efface le flux d'instructions accessible depuis le départ, puis répare les corps de fonctions et réassemble le flux conservé (ClearFlowAndRepairCmd avec clear_data=false, clear_labels=false, repair=true)
• create_function_tag - Créer une définition d'étiquette de fonction à l'échelle du programme avec un commentaire optionnel
• delete_function_tag - Supprimer une définition d'étiquette de fonction à l'échelle du programme
• get_function_tags - Lister toutes les étiquettes attribuées à une fonction spécifique
• list_class_members - Lister les fonctions membres d'une classe C++
• list_function_tags - Lister toutes les définitions d'étiquettes de fonction à l'échelle du programme avec leur nombre d'utilisations
• remove_function_tag - Détacher une ou plusieurs étiquettes d'une fonction
• search_functions_by_tag - Lister toutes les fonctions qui ont une étiquette spécifiée attachée
• set_decompiler_variable_type - Définir le type d'une variable ou d'un paramètre du décompilateur (haut niveau) par nom
• set_function_no_return - Définir l'attribut sans retour
• set_function_tag_comment - Mettre à jour le commentaire/description d'une étiquette de fonction existante à l'échelle du programme
• set_function_this_type - Définir le type du pointeur 'this' implicite pour le décompilateur/base de données (ECX sur x86 __thiscall/__fastcall)
• set_variables - Définir les types et noms de plusieurs variables de manière atomique

Références croisées

• add_memory_reference - Créer une référence croisée définie par l'utilisateur entre deux adresses mémoire que l'analyseur automatique ne peut pas déduire (tables de pointeurs peuplées à l'exécution, vtables, pointeurs de fonction liés tardivement, tables de saut/commutation manquées)
• get_bulk_xrefs - Obtenir les références croisées pour plusieurs adresses
• get_function_xrefs - Obtenir les références croisées d'une fonction
• get_xrefs_from - Obtenir les références depuis une adresse
• get_xrefs_to - Obtenir les références vers une adresse
• remove_reference - Supprimer une ou plusieurs références croisées mémoire d'une adresse à une autre — l'inverse de add_memory_reference

Types de données et structures

• add_struct_field - Ajouter un champ de structure
• analyze_global_completeness - Évaluer l'exhaustivité de la documentation d'une variable globale sur une échelle budgétisée de 0 à 100 — l'analogue pour les adresses de données de analyze_function_completeness
• apply_data_type - Appliquer un type de données
• audit_global - Auditer l'état de documentation d'une variable globale
• audit_globals_in_function - Auditer chaque variable globale référencée dans une fonction en un seul appel
• batch_set_variable_types - Définir plusieurs types de variables
• clone_data_type - Cloner un type de données
• create_array_type - Créer un type tableau
• create_data_type_category - Créer une catégorie de types de données
• create_enum - Créer une énumération
• create_function_signature - Créer un type de signature de fonction
• create_pointer_type - Créer un type pointeur
• create_struct - Créer une structure
• create_typedef - Créer un typedef
• create_union - Créer une union
• delete_data_type - Supprimer un type de données
• embed_struct_field - Remplacer un champ de structure par un type de structure intégré par valeur (par ex.
• get_data_type_size - Obtenir la taille d'un type de données en octets
• get_type_size - Obtenir la taille et les informations d'un type de données
• import_data_types - Importer des types de données depuis un GDT
• list_data_type_categories - Lister les catégories de types de données
• list_data_types - Lister les types de données
• modify_struct_field - Modifier un champ de structure
• modify_struct_field_type - Définir le type d'un champ de structure par nom ou décalage (offset:N)
• move_data_type_to_category - Déplacer un type de données vers une catégorie
• recreate_struct - Remplacer une structure en une étape : supprimer facultativement un type existant du même nom, puis créer avec les champs au format JSON (même forme que create_struct)
• remove_struct_field - Supprimer un champ de structure
• resize_struct - Agrandir ou réduire une structure existante par taille totale en octets
• resolve_duplicate_type - Trouver les types de données en double par nom simple ; supprimer les stubs /Demangler de taille 1 inutilisés lorsqu'un type canonique plus grand existe
• set_function_prototype - Définir le prototype d'une fonction (type de retour, types de paramètres, convention d'appel)
• set_global - Appliquer atomiquement nom + type + commentaire de plaque + longueur de tableau à une variable globale
• set_local_variable_type - Définir le type d'une variable
• set_parameter_type - Définir le type d'un paramètre
• set_variable_storage - Définir le stockage d'une variable
• validate_data_type - Valider la syntaxe d'un type de données
• validate_data_type_exists - Vérifier si un type de données existe
• validate_function_prototype - Valider un prototype de fonction

Renommage et étiquettes

• batch_create_labels - Créer plusieurs étiquettes
• batch_delete_labels - Supprimer plusieurs étiquettes
• batch_rename_function_components - Renommer en lot les composants d'une fonction
• create_label - Créer une étiquette
• delete_label - Supprimer une étiquette à une adresse
• rename_data - Renommer un symbole de données
• rename_external_location - Renommer un emplacement externe
• rename_function - Renommer une fonction par nom
• rename_function_by_address - Renommer une fonction par adresse
• rename_global_variable - Renommer une variable globale
• rename_label - Renommer une étiquette
• rename_or_label - Renommer ou créer une étiquette
• rename_variable - Renommer une variable dans une fonction
• rename_variables - Renommer en lot des variables

Commentaires et marque-pages

• batch_set_comments - Définir plusieurs commentaires
• clear_function_comments - Effacer tous les commentaires d'une fonction
• delete_bookmark - Supprimer un marque-page
• get_comment - Obtenir les commentaires de listing (plaque/pré/fin de ligne/post/répétable) à N'IMPORTE QUELLE adresse, y compris les adresses de données (contrairement à get_plate_comment qui nécessite une fonction)
• get_plate_comment - Obtenir un commentaire de plaque
• set_bookmark - Définir un marque-page
• set_comment - Définir un commentaire de listing d'un type donné (plaque/pré/fin de ligne/post/répétable) à N'IMPORTE QUELLE adresse, y compris les adresses de données
• set_decompiler_comment - Définir un PRE_COMMENT
• set_disassembly_comment - Définir un EOL_COMMENT
• set_plate_comment - Définir un commentaire de plaque

Analyse

• analyze_api_call_chains - Analyser les chaînes d'appels API
• analyze_call_graph - Analyser les motifs du graphe d'appel de fonction
• analyze_control_flow - Analyser le flux de contrôle
• analyze_data_region - Analyser une région de données
• analyze_dataflow - Tracer la propagation de valeurs à travers une fonction (graphe PCode, avant/arrière)
• analyze_for_documentation - Analyse composite de documentation RE (décompilation + classification + variables + exhaustivité)
• analyze_function_complete - Analyse complète d'une fonction en un seul appel
• analyze_function_completeness - Analyser l'exhaustivité de la documentation
• analyze_struct_field_usage - Analyser l'utilisation des champs de structure
• apply_data_classification - Appliquer une classification de données
• batch_analyze_completeness - Analyser en lot l'exhaustivité pour plusieurs fonctions
• batch_apply_documentation - Appliquer toute la documentation à une fonction en un seul appel
• batch_decompile - Décompiler plusieurs fonctions à la fois
• can_rename_at_address - Vérifier si une adresse peut être renommée
• clear_instruction_flow_override - Effacer une redéfinition de flux
• configure_analyzer - Configurer un plugin d'analyse
• create_function - Créer une fonction à une adresse
• create_memory_block - Créer un bloc mémoire
• delete_function - Supprimer une fonction à une adresse
• detect_array_bounds - Détecter les limites de tableau
• detect_crypto_constants - Détecter les constantes cryptographiques
• detect_malware_behaviors - Détecter les comportements de malware
• extract_iocs_with_context - Extraire les indicateurs de compromission (IOC) avec contexte
• find_anti_analysis_techniques - Trouver les techniques anti-analyse
• find_code_gaps - Trouver les lacunes d'octets indéfinis entre les fonctions dans la mémoire exécutable
• find_dead_code - Trouver du code mort
• find_next_undefined_function - Trouver la prochaine fonction non définie
• get_assembly_context - Obtenir le contexte assembleur
• get_field_access_context - Obtenir le contexte d'accès au champ
• get_function_pcode - Dump le P-code brut d'une fonction (issue #192)
• inspect_memory_content - Inspecter les octets mémoire
• list_analyzers - Lister les plugins d'analyse disponibles
• read_memory - Lire la mémoire brute
• run_analysis - Exécuter une analyse automatique sur le programme actuel
• search_instructions - Rechercher des instructions par mnémonique et/ou sous-chaîne d'opérande
• suggest_field_names - Suggérer des noms de champs

Documentation et archive inter-binaires

• archive_ingest_function - Ingérer la documentation d'une seule fonction dans l'archive inter-versions (re_kb.functions sur bsim Postgres)
• archive_ingest_program - Ingérer en masse toutes les fonctions d'un programme dans l'archive de documentation inter-versions
• batch_string_anchor_report - Rapport des chaînes du fichier source et de leurs fonctions FUN_*
• bulk_fuzzy_match - Correspondance floue inter-binaire en masse
• find_similar_functions_fuzzy - Correspondance floue inter-binaire de fonctions
• merge_program_documentation - Fusion en masse : copier toute la documentation RE (noms de fonctions, signatures, commentaires de plaque, commentaires d'instructions en EOL/PRE/POST, étiquettes non par défaut et symboles globaux) d'un programme à un autre aux adresses correspondantes

Transfert d'utilitaires et de documentation

• apply_function_documentation - Appliquer la documentation d'une fonction
• check_connection - Point de terminaison de vérification d'état
• compare_programs_documentation - Comparer la documentation entre programmes
• convert_number - Convertir un nombre entre bases
• diff_functions - Différencier deux fonctions
• find_undocumented_by_string - Trouver les fonctions non documentées référençant une chaîne
• get_bulk_function_hashes - Obtenir les hachages de fonctions en masse
• get_function_documentation - Exporter la documentation d'une fonction
• get_function_hash - Obtenir le hachage d'une fonction
• get_function_signature - Obtenir la signature d'une fonction
• get_metadata - Obtenir les métadonnées du programme
• get_version - Obtenir la version du plugin
• health - Point de terminaison de vérification d'état pour le serveur sans tête
• mcp_health - Santé du serveur HTTP : statistiques du pool, temps d'activité, mémoire, nombre de requêtes actives
• mcp_schema - Schéma d'API lisible par machine avec métadonnées de point de terminaison
• tool_goto_address - Naviguer dans le listing CodeBrowser et le décompilateur vers une adresse spécifique
• tool_launch_codebrowser - Ouvrir un fichier dans CodeBrowser, en lançant un nouveau si nécessaire
• tool_running_tools - Lister toutes les fenêtres d'outils Ghidra en cours d'exécution

Émulation

• emulate_function - Émuler une seule fonction avec des entrées registre/mémoire contrôlées
• emulate_hash_batch - Résolution par force brute de hachage d'API

Scripting

• run_ghidra_script - Exécuter un script avec capture de sortie
• run_script_inline - Exécuter du code de script en ligne

Serveur Ghidra et contrôle de version

• server_admin_set_permissions - Définir les permissions utilisateur sur un dépôt
• server_admin_terminate_all_checkouts - Terminer tous les extractions dans un dossier de manière récursive
• server_admin_terminate_checkout - Terminer tous les extractions sur un seul fichier
• server_admin_users - Lister tous les utilisateurs sur le serveur
• server_authenticate - Enregistrer les identifiants du serveur pour l'authentification programmatique
• server_checkouts - Lister tous les fichiers extraits dans un dossier, y compris les extractions côté serveur
• server_connect - Se connecter à un serveur Ghidra
• server_disconnect - Se déconnecter du serveur Ghidra
• server_repositories - Lister les dépôts sur le serveur connecté
• server_repository_create - Créer un nouveau dépôt sur le serveur
• server_repository_file - Obtenir les informations d'un fichier depuis un dépôt serveur
• server_repository_files - Lister les fichiers dans un dossier de dépôt serveur
• server_version_control_add - Ajouter un fichier au contrôle de version
• server_version_control_checkin - Réintégrer un fichier sous contrôle de version
• server_version_control_checkout - Extraire un fichier sous contrôle de version
• server_version_control_undo_checkout - Annuler une extraction de fichier
• server_version_history - Obtenir l'historique des versions d'un fichier

Débogueur (Ghidra TraceRmi — interface graphique uniquement)

Sur les hôtes Windows où le proxy de débogueur WinDbg du pont est actif (GHIDRA_DEBUGGER_URL), les noms en conflit reçoivent un suffixe _2 (par ex. debugger_status_2).

• debugger_dynamic_to_static - Traduire une adresse dynamique d'exécution de la trace actuelle vers une adresse de programme Ghidra statique
• debugger_interrupt - Interrompre (casser dans) la cible en cours d'exécution
• debugger_launch - Lancer un exécutable via le lanceur de débogueur Trace RMI de Ghidra
• debugger_launch_offers - Lister les options disponibles de lancement/attachement du débogueur pour le programme actuel
• debugger_list_breakpoints - Lister tous les points d'arrêt dans la trace actuelle
• debugger_modules - Lister les modules (DLLs/EXEs) chargés dans le processus débogué
• debugger_read_memory - Lire la mémoire du processus débogué
• debugger_registers - Lire les registres CPU du snapshot de trace de débogage actuel
• debugger_remove_breakpoint - Supprimer un point d'arrêt à une adresse
• debugger_resume - Reprendre l'exécution du processus débogué
• debugger_set_breakpoint - Définir un point d'arrêt d'exécution logiciel à une adresse dans la trace
• debugger_stack_trace - Obtenir la trace de la pile d'appels pour le thread actuel
• debugger_static_to_dynamic - Traduire une adresse de programme Ghidra statique en une adresse dynamique d'exécution dans la trace actuelle
• debugger_status - Obtenir l'état du débogueur : trace active, thread, état d'exécution, nombre de modules
• debugger_step_into - Pas à pas entrant dans l'instruction suivante (suit les appels)
• debugger_step_out - Sortir de la fonction actuelle (exécuter jusqu'au retour)
• debugger_step_over - Pas à pas franchissant l'instruction suivante (ne suit pas les appels)
• debugger_traces - Lister toutes les traces de débogage ouvertes

Système

• prompt_policy - Activer, désactiver temporairement ou interroger la gestion des invites d'automatisation à portée

Outils statiques BridgeDéfini dans le pont Python lui-même (découverte d'instances, gestion de groupes d'outils) ; toujours disponible avant même une connexion Ghidra. Le pont sert également de proxy pour 22 outils WinDbg debugger_* lorsque GHIDRA_DEBUGGER_URL pointe vers le serveur de débogueur autonome.

• check_tools - Signale quels outils sont actuellement enregistrés et appelables
• connect_instance - Connecte le pont à une instance Ghidra spécifique
• import_file - Importe un binaire depuis le disque dans le projet courant et l'ouvre
• list_instances - Découvre les instances Ghidra MCP en cours d'exécution (scan des ports UDS + TCP)
• list_tool_groups - Liste les groupes d'outils et leur état de chargement
• load_tool_group - Enregistre les outils dynamiques d'un groupe d'outils auprès du client MCP
• search_tools - Recherche dans le catalogue complet d'outils par mot-clé
• unload_tool_group - Désenregistre les outils dynamiques d'un groupe d'outils

See CHANGELOG.md for version history.

🏗️ Architecture```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### Composants

- **python/bridge_mcp_ghidra/** — Paquet serveur MCP Python (distribué sous forme de la roue `ghidra-mcp-bridge` ; script console `bridge-mcp-ghidra`) qui traduit le protocole MCP en appels HTTP (225 entrées de catalogue)
- **GhidraMCP.jar** — Plugin Ghidra qui expose les capacités d'analyse via HTTP (175 points d'accès GUI)
- **GhidraMCPHeadlessServer** — Serveur headless autonome — 183 points d'accès, aucune GUI requise
- **ghidra_scripts/** — Collection de scripts d'automatisation pour les tâches courantes

## 🔧 Développement

### Construction à partir des sources```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

Le système de build officiel est actuellement Maven. tools.setup, les tâches VS Code et le flux de déploiement documenté construisent via pom.xml et écrivent les artefacts dans target/. build.gradle reste dans le dépôt comme solution de repli manuelle pour les utilisateurs directs de Ghidra/Gradle, mais ce n'est pas le chemin principal.

Référence des commandes

Indicateurs courants acceptés par la plupart des commandes :

Les niveaux de test de déploiement sont facultatifs car les niveaux de benchmark peuvent importer/réinitialiser Benchmark.dll et BenchmarkDebug.exe dans le projet Ghidra actif. Utilisez --test release avant de préparer les versions, ou définissez GHIDRA_MCP_DEPLOY_TESTS=release dans un fichier .env local lorsque vous souhaitez que chaque déploiement sur votre machine exécute la régression de benchmark en direct. Voir Testing and Release Regression.```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### Structure du projet```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

Dépendances des bibliothèques

Les JARs de Ghidra doivent être installés dans votre dépôt Maven local (~/.m2/repository) avant la compilation. Il s'agit d'une configuration unique par machine, à refaire lorsque votre version de Ghidra change. -Deploy installe désormais ces dépendances automatiquement par défaut.

L'outil impose une cohérence de version entre :

• pom.xml (ghidra.version)
• le segment de version de --ghidra-path (par ex. ghidra_12.1.2_PUBLIC)

Si ceux-ci ne correspondent pas, le déploiement échoue rapidement avec un message d'erreur clair.

Dépannage : Incohérence de version

Si vous rencontrez une erreur d'incohérence de version, alignez les deux valeurs :

1. pom.xml → ghidra.version
2. le segment de version de --ghidra-path (ghidra_X.Y.Z_PUBLIC)

Puis relancez :```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Please provide the Markdown content to translate.```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

Bibliothèques requises (14 JARs, ~37 Mo) :

Remarque : Les bibliothèques NE sont PAS incluses dans le dépôt (voir .gitignore). Vous devez les installer à partir de votre installation de Ghidra avant de compiler.

Point d'entrée d'automatisation :

• python -m tools.setup est l'interface prise en charge pour la configuration, la compilation, le déploiement et la gestion des versions
• utilisez ensure-prereqs, build, deploy, preflight, clean-all et bump-version directement
• ces commandes utilisent actuellement Maven comme backend de compilation Java canonique

Fonctionnalités de développement

• Déploiement automatisé : Script de déploiement tenant compte des versions
• Opérations par lots : Réduit les appels API de 93 %
• Transactions atomiques : Sémantique du tout ou rien
• Journalisation complète : Capacités de débogage et de trace

📚 Documentation

Documentation de base

• Index de la documentation - Navigation complète dans la documentation
• Structure du projet - Guide d'organisation du projet
• Tests et régression de version - Tests locaux, CI, régression Ghidra en direct et portes de version
• Conventions de nommage - Normes de nommage du code
• Notation hongroise - Guide de nommage des variables

Invites de workflow IA

• Documentation de fonction V5 — Workflow principal : processus en 7 étapes avec notation hongroise, audit de type et score de vérification
• Documentation par lots V5 — Distribution parallèle de sous-agents pour le traitement multi-fonctions
• Découverte de code orphelin — Scanner automatisé pour les fonctions non découvertes
• Investigation des types de données — Découverte systématique de structures
• Correspondance inter-versions — Correspondance de fonctions basée sur les hachages
• Invite de démarrage rapide — Workflow simplifié pour débutants
• Toutes les invites — Index complet des invites

Historique des versions

• Journal des modifications complet - Notes de version de toutes les versions
• Notes de version - Documentation détaillée des versions

🐳 Serveur sans tête (Docker)

GhidraMCP inclut un mode serveur sans tête pour l'analyse automatisée sans l'interface graphique de Ghidra.

Démarrage rapide avec Docker```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### Workflow d'API Headless```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

Points d'accès headless clés

Configuration

Variables d'environnement pour Docker :

• GHIDRA_MCP_PORT - Port du serveur (par défaut : 8089)
• GHIDRA_MCP_BIND_ADDRESS - Adresse de liaison (par défaut : 0.0.0.0 dans Docker)
• JAVA_OPTS - Options JVM (par défaut : -Xmx4g -XX:+UseG1GC)

🤝 Contribuer

Voir CONTRIBUTING.md pour les directives de contribution détaillées.

Démarrage rapide

1. Forker le dépôt
2. Créer une branche de fonctionnalité (git checkout -b feature/amazing-feature)
3. Compiler et tester vos modifications (mvn clean package assembly:single -DskipTests ou GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. Mettre à jour la documentation si nécessaire
5. Commiter vos modifications (git commit -m 'Add amazing feature')
6. Pousser sur la branche (git push origin feature/amazing-feature)
7. Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence Apache 2.0 - voir le fichier LICENSE pour les détails.

🏆 Statut de production

Voir CHANGELOG.md pour l'historique des versions et les notes de version.

🙏 Remerciements

Ce projet a été initialement dérivé de LaurieWired/GhidraMCP en août 2025 et a depuis été considérablement réécrit et étendu. Nous reconnaissons le travail original de LaurieWired comme point de départ. Voir NOTICE pour l'attribution de licence.

👥 Contributeurs

Ce projet a bénéficié du travail de contributeurs dévoués :

Contributeurs principaux

@heeen — Contributions significatives incluant :

• Correspondance floue de fonctions et diff structuré pour la comparaison croisée de binaires (#13)
• Améliorations de l'exécution de scripts et corrections de bugs (#12)
• Nouveaux points d'accès API : save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• Vision architecturale : conception pilotée par annotations, transport UDS, propositions d'optimisation du pont Python

@huehuehuehueing — Contributions significatives incluant :

• Prise en charge du préfixe d'espace d'adressage — ajout de la syntaxe <espace>:<hex> (par exemple, mem:1000, code:ff00) à l'analyse des adresses sur toute la surface des points d'accès, déverrouillant les cibles multi-espaces comme le firmware embarqué (#84, ferme #65)

• Paramètre program optionnel + corrections du schéma des paramètres requis — a rendu program optionnel sur chaque point d'accès avec un repli currentProgram raisonnable, et a corrigé plusieurs bugs de schéma requis-vs-optionnel que le catalogue avait hérités (#92)

• A amorcé #44 (outils de type de données / énumération) — le problème qui a motivé la couche d'application de énumérations + structures v5.0

• Ghidra Team - Pour la plateforme de rétro-ingénierie incroyable

• Model Context Protocol - Pour le cadre d'intégration IA standardisé

• Contributeurs - Pour les tests, les retours et les améliorations

🔗 Projets connexes

• re-universe — Plateforme Ghidra BSim PostgreSQL pour l'analyse de similarité binaire à grande échelle. Se marie parfaitement avec GhidraMCP pour les workflows de rétro-ingénierie pilotés par IA.
• cheat-engine-server-python — Serveur MCP pour l'analyse dynamique de la mémoire et le débogage.

Prêt pour un déploiement en production avec une fiabilité de niveau entreprise et des capacités complètes d'analyse binaire.