PyGhidra-MCP - Serveur Ghidra Model Context Protocol

Vue d'ensemble

pyghidra-mcp est un serveur Model Context Protocol (MCP) en ligne de commande qui apporte toute la puissance analytique de Ghidra, une suite robuste de rétro-ingénierie logicielle (SRE), dans le monde des agents intelligents et des outils basés sur les LLM. Il relie le ProgramAPI et le FlatProgramAPI de Ghidra à Python via pyghidra et jpype, puis expose cette fonctionnalité 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 de rétro-ingénierie approfondies et à s'intégrer dans des flux de travail assistés par IA.

pyghidra-mcp prend désormais en charge deux modes de fonctionnement :

le mode headless pour l'analyse et l'automatisation pilotées par CLI
le 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, signalements de bugs, demandes de fonctionnalités et contributions de code.

Encore un autre MCP pour Ghidra ?

Oui, le ghidra-mcp original est fantastique. Mais pyghidra-mcp adopte une approche différente :

🐍 Headless d'abord, compatible GUI – Exécutez entièrement via CLI pour une automatisation rationalisée, ou lancez 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 – Conçu 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 simultanée de tous les binaires d'un projet Ghidra.
🤖 Prêt pour les agents – Conçu pour les flux de travail pilotés par 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 floue rapide parmi les fonctions décompilées, les commentaires et les symboles—parfait pour l'exploration de pseudo-C et le triage piloté par agents.

Ce projet offre une expérience Python-first optimisée pour le développement local, les environnements headless et les flux de travail testables.

Schémas d'installation

Comment les éléments se connectent```mermaid

flowchart LR subgraph Clients["Clients"] Agent["MCP host / agent"] Cli["pyghidra-mcp-cli"] User["Ghidra user"] end

subgraph Process["pyghidra-mcp process"]
    Transport["stdio or streamable-http"]
    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 -->|"stdio or HTTP"| 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 only"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Stdio["pyghidra-mcp -t stdio<br/>or -t 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 tête (Headless MCP) : utilisez stdio pour les hôtes MCP locaux, ou streamable-http lorsque plusieurs clients doivent partager un même projet Ghidra de longue durée.
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 envoyez des commandes terminal à ce serveur en cours d'exécution.

Architecture détaillée et surface d'outils

```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"]
    FastMcp["FastMCP 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 --> Stdio
Agent --> Http
Automation --> Stdio
Automation --> Http
Automation --> Sse
Cli --> Http

Stdio --> FastMcp
Http --> FastMcp
Sse --> FastMcp

FastMcp --> Context
Context --> PyGhidra
PyGhidra --> Jpype
Jpype --> Project
Project --> Programs
Context --> Indexing
Indexing --> Search

FastMcp --> Tools
Tools --> Context
GuiOnly -.-> CodeBrowser
Context -.-> CodeBrowser

</details>

## Sommaire

- [PyGhidra-MCP - Ghidra Model Context Protocol Server](#pyghidra-mcp---ghidra-model-context-protocol-server)
    - [Aperçu](#overview)
  - [Encore un autre MCP Ghidra ?](#yet-another-ghidra-mcp)
  - [Schémas de configuration](#setup-diagrams)
    - [Comment les composants se connectent](#how-the-pieces-connect)
    - [Choisir un mode](#choosing-a-mode)
  - [Sommaire](#contents)
  - [Pour commencer](#getting-started)
  - [Optimisé pour les agents](#optimized-for-agents)
  - [Client CLI](#cli-client)
    - [Installation](#installation)
    - [Démarrage rapide avec CLI](#quick-start-with-cli)
  - [Création, gestion et ouverture de projets existants](#project-creation-management-and-opening-existing-projects)
    - [Création de nouveaux projets](#creating-new-projects)
      - [Structure de projet autonome](#self-contained-project-structure)
      - [Création de projet de base](#basic-project-creation)
      - [Création de projet personnalisé](#custom-project-creation)
      - [Création de plusieurs projets liés](#creating-multiple-related-projects)
    - [Ouverture de projets Ghidra existants](#opening-existing-ghidra-projects)
      - [Ouverture via fichier .gpr](#opening-by-gpr-file)
    - [Mode GUI](#gui-mode)
    - [Paramètres par défaut au démarrage et grands projets](#startup-defaults-and-large-projects)
  - [Développement](#development)
    - [Configuration](#setup)
    - [Tests et qualité](#testing-and-quality)
  - [API](#api)
    - [Outils](#tools)
      - [Opérations par lots](#batch-operations)
      - [Outils de lecture / d'analyse](#read--analysis-tools)
      - [Opérations sur les projets](#project-operations)
      - [Outils d'édition / de mutation](#edit--mutation-tools)
      - [Outils de contrôle GUI (uniquement `--gui`)](#gui-control-tools---gui-only)
  - [Utilisation](#usage)
    - [Cartographie des binaires avec Docker](#mapping-binaries-with-docker)
    - [Utilisation avec OpenWeb-UI et MCPO](#using-with-openweb-ui-and-mcpo)
      - [Avec `uvx`](#with-uvx)
      - [Avec Docker](#with-docker)
    - [Entrée/sortie standard (stdio)](#standard-inputoutput-stdio)
      - [Python](#python)
      - [Docker](#docker)
    - [HTTP streamable](#streamable-http)
      - [Python](#python-1)
      - [Docker](#docker-1)
    - [Événements envoyés par le serveur (SSE)](#server-sent-events-sse)
      - [Python](#python-2)
      - [Docker](#docker-2)
  - [Intégrations](#integrations)
    - [Claude Desktop](#claude-desktop)
  - [Inspiration](#inspiration)
  - [Contribution, communauté et exécution depuis les sources](#contributing-community-and-running-from-source)
    - [Processus de contribution](#contributor-workflow)

## Pour commencer

Exécutez le [package Python](https://pypi.org/p/pyghidra-mcp) en tant que commande CLI avec [`uv`](https://docs.astral.sh/uv/guides/tools/) :```bash
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default

Le mode GUI est le bon choix lorsque vous souhaitez : - ouvrir ou changer de programme dans CodeBrowser - naviguer dans le listing jusqu'à 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 grands projets `pyghidra-mcp` ne requiert 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. C'est important pour les grands projets : - le démarrage d'un projet contenant de nombreux binaires ne doit pas bloquer le démarrage du serveur - `--wait-for-analysis` est disponible lorsque vous souhaitez un projet entièrement analysé avant de servir les requêtes - pour les grands projets existants, attendez-vous à ce que la disponibilité de l'analyse et de l'indexation varie selon le binaire Limitation actuelle : - l'état de l'analyse Ghidra et l'état de l'indexation MCP sont séparés - un binaire peut être entièrement analysé dans Ghidra alors que `search_strings` ou `search_code` sémantique attendent encore l'indexation côté MCP - c'est plus visible lors de l'ouverture de grands projets existants En pratique : - la décompilation, la navigation, le renommage et les commentaires peuvent toujours fonctionner pour un binaire pendant que les fonctions de recherche gourmandes en indexation rattrapent leur retard - si la latence de démarrage importe plus que la disponibilité immédiate de la recherche, conservez la valeur par défaut `--no-wait-for-analysis` - si la disponibilité immédiate importe 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/HEAD/: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` : Exécuter la suite de tests complète (tests unitaires et d'intégration). - `make test-unit` : Exécuter les tests unitaires. - `make test-integration` : Exécuter les tests d'intégration. - `make test-integration-fast` : Exécuter le test de fumée d'intégration léger utilisé par pre-commit. - `make test-integration-gui` : Exécuter les tests d'intégration GUI. Nécessite une installation Ghidra fonctionnelle et le support GUI. - `make lint` : Vérifier le style de code avec `ruff`. - `make format` : Formater le code avec `ruff`. - `make typecheck` : Exécuter des vérifications statiques légères avec `ruff`. - `make check` : Exécuter toutes les vérifications de qualité. - `make dev` : Exécuter le workflow 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`, les tests unitaires et un test de fumée d'intégration léger - GitHub Actions : couverture complète de l'intégration Linux sans interface graphique, interface graphique Linux sous `Xvfb`, couverture CLI et tests de fumée macOS actuels - CI planifiée : couverture de compatibilité avec d'anciennes versions de macOS / Ghidra - local/manuel : débogage GUI plus lourd spécifique à l'environnement et vérifications de cohérence des versions ## API ### Outils Permettent aux LLM d'effectuer des actions, de réaliser 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'appel 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"] }

#### 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 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, symboles ou adresses. Accepte une cible unique ou une liste pour la consultation par lot. - `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 la décompilation par lot. Les indicateurs de réponse enrichie associent les fonctions appelées (callees), les chaînes et/ou les références croisées (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 tous les symboles exportés d'un binaire spécifié (les expressions régulières sont prises en charge pour la requête). - `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Liste toutes les fonctions et tous les symboles importés pour un binaire spécifié (les expressions régulières sont prises en charge pour la requête). - `read_bytes(binary_name: str, address: str, size: int = 32)`: Lit les octets bruts de la 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 de caractères 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 d'expressions régulières (par ex. `^main$`, `func.*one`) avec une correspondance insensible à la casse, ou les requêtes de sous-chaîne simples. Définissez `functions_only=True` pour exclure les étiquettes, les variables et les autres symboles non associés à des fonctions. #### Opérations sur le projet - `import_binary(binary_path: str)`: Importe un binaire à partir d'un chemin désigné dans le projet Ghidra courant. Si le chemin est un répertoire, il analyse et importe récursivement tous les fichiers binaires pris en charge, en préservant la structure des répertoires dans le projet Ghidra. - `list_project_binaries()`: Liste les binaires du projet Ghidra courant. En mode GUI, cela inclut les binaires du projet présents 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 empreintes de fichier. - `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 dans une fonction spécifique. Si le nom est absent 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 dans une fonction spécifique. Si le nom est absent ou ambigu dans cette fonction, l'outil renvoie une erreur au lieu de deviner. `type_name` est analysé par l'analyseur de types de données de Ghidra via le 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 sous-jacente de l'analyseur ou d'application 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 des commentaires de listing peuvent être des adresses, des symboles ou des fonctions. Les valeurs `comment_type` prises en charge 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)`: Définit un programme ouvert comme 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 jusqu'à une adresse ou une fonction. `target_type` doit être `address` ou `function`. ## Utilisation Ce package 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 autre gestionnaire de packages 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.

Populaires

pyghidra-mcp

Optimisé pour les agents

Client CLI

Installation

Démarrage rapide avec CLI

Création, gestion et ouverture de projets existants

Création de nouveaux projets

Structure de projet autonome

Création de projet de base```bash

Create a new project with default settings

Creates:

Créer plusieurs projets liés```bash

Create separate projects for different analysis focuses

Project for suspicious binaries

Project for packed malware

Mode GUI

Mapper les binaires avec Docker

Create and populate the new directory

Run the Docker container with volume mapping

Avec Docker

Docker

Événements envoyés par le serveur (SSE)

Python```bash

Intégrations

Claude Desktop