PyGhidra-MCP - Servidor del Protocolo de Contexto del Modelo de Ghidra

Visión general

pyghidra-mcp es un servidor de línea de comandos del Protocolo de Contexto del Modelo (MCP) que trae todo el poder analítico de Ghidra, un robusto conjunto de herramientas de ingeniería inversa de software (SRE), al mundo de los agentes inteligentes y las herramientas basadas en LLM. Conecta la ProgramAPI y la FlatProgramAPI de Ghidra con Python usando pyghidra y jpype, y luego expone esa funcionalidad a través del Protocolo de Contexto del Modelo.

MCP es una interfaz unificada que permite a los modelos de lenguaje, herramientas de desarrollo (como VS Code) y agentes autónomos acceder a contexto estructurado, invocar herramientas y colaborar inteligentemente. Piensa en MCP como el puente entre potentes herramientas de análisis y el ecosistema LLM.

Con pyghidra-mcp, Ghidra se convierte en un backend inteligente—listo para responder a consultas ricas en contexto, automatizar tareas profundas de ingeniería inversa e integrarse en flujos de trabajo asistidos por IA.

pyghidra-mcp ahora soporta dos modos de operación:

modo headless para análisis y automatización desde la línea de comandos
modo --gui, que inicia Ghidra a través de pyghidra-mcp y comparte el estado del programa en vivo con la GUI en ejecución

[!NOTE] Este proyecto beta está en desarrollo activo. Nos encantaría recibir tus comentarios, informes de errores, solicitudes de funciones y código.

¿Otro MCP de Ghidra?

Sí, el ghidra-mcp original es fantástico. Pero pyghidra-mcp adopta un enfoque diferente:

🐍 Prioriza el modo headless, con capacidad de GUI – Ejecútalo completamente desde la línea de comandos para una automatización optimizada, o inicia Ghidra con --gui cuando quieras navegación y edición en vivo en la GUI.
🔁 Diseñado para automatización – Ideal para integrarse con LLMs, pipelines de CI y herramientas que necesitan comportamiento repetible.
✅ Amigable con CI/CD – Construido con pruebas unitarias y de integración robustas tanto para sesiones de cliente como de servidor.
🚀 Inicio rápido – El inicio asíncrono permite que el servidor comience a manejar solicitudes mientras los binarios aún se analizan en segundo plano. Soporta lanzamiento rápido desde la línea de comandos con configuración mínima.
📦 Análisis a nivel de proyecto – Permite la ingeniería inversa concurrente de todos los binarios en un proyecto de Ghidra
🤖 Listo para agentes – Construido para flujos de trabajo impulsados por agentes inteligentes y automatización de ingeniería inversa a gran escala.
🔍 Búsqueda semántica de código – Utiliza embeddings vectoriales (a través de ChromaDB) para permitir búsquedas rápidas y difusas en funciones descompiladas, comentarios y símbolos—perfecto para exploración de pseudo-C y clasificación impulsada por agentes.

Este proyecto ofrece una experiencia centrada en Python optimizada para el desarrollo local, entornos sin interfaz gráfica y flujos de trabajo comprobables.

Diagramas de configuración

Cómo se conectan las piezas```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

### Eligiendo un Modo```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"]

Headless MCP: usa stdio para hosts MCP locales, o streamable-http cuando varios clientes necesitan el mismo proyecto Ghidra de larga duración.
Modo GUI: pyghidra-mcp lanza Ghidra, abre el proyecto y expone herramientas adicionales que dirigen el CodeBrowser en la misma JVM.
Cliente CLI: pyghidra-mcp-cli es un cliente HTTP. Primero inicia un servidor streamable-http, luego ejecuta comandos de terminal contra ese servidor en ejecución.

Arquitectura detallada y superficie de herramientas

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

## Contenido

- [PyGhidra-MCP - Servidor de Protocolo de Contexto de Modelo Ghidra](#pyghidra-mcp---ghidra-model-context-protocol-server)
    - [Descripción general](#overview)
  - [¿Otro Ghidra MCP?](#yet-another-ghidra-mcp)
  - [Diagramas de configuración](#setup-diagrams)
    - [Cómo se conectan las piezas](#how-the-pieces-connect)
    - [Elegir un modo](#choosing-a-mode)
  - [Contenido](#contents)
  - [Primeros pasos](#getting-started)
  - [Optimizado para agentes](#optimized-for-agents)
  - [Cliente CLI](#cli-client)
    - [Instalación](#installation)
    - [Inicio rápido con CLI](#quick-start-with-cli)
  - [Creación, gestión y apertura de proyectos existentes](#project-creation-management-and-opening-existing-projects)
    - [Crear nuevos proyectos](#creating-new-projects)
      - [Estructura de proyecto autocontenida](#self-contained-project-structure)
      - [Creación básica de proyectos](#basic-project-creation)
      - [Creación personalizada de proyectos](#custom-project-creation)
      - [Creación de múltiples proyectos relacionados](#creating-multiple-related-projects)
    - [Apertura de proyectos Ghidra existentes](#opening-existing-ghidra-projects)
      - [Apertura mediante archivo .gpr](#opening-by-gpr-file)
    - [Modo GUI](#gui-mode)
    - [Valores predeterminados de inicio y proyectos grandes](#startup-defaults-and-large-projects)
  - [Desarrollo](#development)
    - [Configuración](#setup)
    - [Pruebas y calidad](#testing-and-quality)
  - [API](#api)
    - [Herramientas](#tools)
      - [Operaciones por lotes](#batch-operations)
      - [Herramientas de lectura/análisis](#read--analysis-tools)
      - [Operaciones de proyecto](#project-operations)
      - [Herramientas de edición/mutación](#edit--mutation-tools)
      - [Herramientas de control GUI (solo `--gui`)](#gui-control-tools---gui-only)
  - [Uso](#usage)
    - [Mapeo de binarios con Docker](#mapping-binaries-with-docker)
    - [Uso con OpenWeb-UI y MCPO](#using-with-openweb-ui-and-mcpo)
      - [Con `uvx`](#with-uvx)
      - [Con Docker](#with-docker)
    - [Entrada/Salida estándar (stdio)](#standard-inputoutput-stdio)
      - [Python](#python)
      - [Docker](#docker)
    - [HTTP transmisible](#streamable-http)
      - [Python](#python-1)
      - [Docker](#docker-1)
    - [Eventos enviados por el servidor (SSE)](#server-sent-events-sse)
      - [Python](#python-2)
      - [Docker](#docker-2)
  - [Integraciones](#integrations)
    - [Claude Desktop](#claude-desktop)
  - [Inspiración](#inspiration)
  - [Contribución, comunidad y ejecución desde el código fuente](#contributing-community-and-running-from-source)
    - [Flujo de trabajo del contribuyente](#contributor-workflow)

## Primeros pasos

Ejecuta el [paquete de Python](https://pypi.org/p/pyghidra-mcp) como un comando CLI usando [`uv`](https://docs.astral.sh/uv/guides/tools/):```bash
uvx pyghidra-mcp # Creates pyghidra_mcp_projects directory by default

El modo GUI es la opción correcta cuando deseas: - abrir o cambiar programas en CodeBrowser - navegar en el listado hacia una función o dirección - renombrar funciones o agregar comentarios y ver inmediatamente esos cambios en Ghidra ### Valores Predeterminados de Inicio y Proyectos Grandes `pyghidra-mcp` no requiere `--wait-for-analysis` por defecto. El servidor puede iniciar mientras el análisis y la indexación del lado de MCP continúan en segundo plano. Esto es importante para proyectos grandes: - iniciar un proyecto con muchos binarios no necesita bloquear el inicio del servidor - `--wait-for-analysis` está disponible cuando deseas un proyecto completamente analizado antes de atender solicitudes - para proyectos grandes existentes, espera que la preparación del análisis y la indexación varíe según el binario Limitación actual: - El estado de análisis de Ghidra y el estado de indexación de MCP están separados - un binario puede estar completamente analizado en Ghidra mientras `search_strings` o `search_code` semántico aún esperan la indexación del lado de MCP - esto es más notable al abrir proyectos existentes más grandes En la práctica: - la descompilación, navegación, renombrado y comentarios aún pueden funcionar para un binario mientras las funciones de búsqueda intensiva en indexación se ponen al día - si la latencia de inicio importa más que la preparación inmediata de búsqueda, mantén el valor predeterminado `--no-wait-for-analysis` - si la preparación inmediata importa más que el tiempo de inicio, usa `--wait-for-analysis` ## Desarrollo Este proyecto utiliza un `Makefile` para agilizar el desarrollo y las pruebas. `ruff` se utiliza para linting y formateo, y los hooks de `pre-commit` se utilizan para garantizar la calidad del código. ### Configuración 1. **Instalar `uv`**: Si no tienes `uv` instalado, puedes instalarlo usando pip: ```bash pip install uv ``` O sigue la guía oficial de instalación de `uv`: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/) 2. **Crear un entorno virtual e instalar dependencias**: ```bash make dev-setup source ./.venv/bin/activate ``` 3. **Establecer la variable de entorno de Ghidra**: Descarga e instala Ghidra, luego establece la variable de entorno `GHIDRA_INSTALL_DIR` en tu directorio de instalación 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) ``` ### Pruebas y Calidad El `Makefile` proporciona varios objetivos para pruebas y calidad del código: - `make run`: Ejecutar el servidor MCP. - `make test`: Ejecutar la suite completa de pruebas (unitarias y de integración). - `make test-unit`: Ejecutar pruebas unitarias. - `make test-integration`: Ejecutar pruebas de integración. - `make test-integration-fast`: Ejecutar la prueba de humo de integración ligera utilizada por pre-commit. - `make test-integration-gui`: Ejecutar pruebas de integración de GUI. Requiere una instalación funcional de Ghidra y soporte de GUI. - `make lint`: Verificar el estilo del código con `ruff`. - `make format`: Formatear código con `ruff`. - `make typecheck`: Ejecutar comprobaciones estáticas ligeras con `ruff`. - `make check`: Ejecutar todas las comprobaciones de calidad. - `make dev`: Ejecutar el flujo de trabajo de desarrollo (formatear y verificar). - `make build`: Construir paquetes de distribución. - `make clean`: Limpiar artefactos de compilación y caché. División recomendada: - pre-commit: `ruff`, `pyright`, pruebas unitarias y una prueba de humo de integración ligera - GitHub Actions: cobertura completa de integración en Linux sin cabeza, GUI de Linux bajo `Xvfb`, cobertura de CLI y pruebas de humo actuales de macOS - CI programada: cobertura de compatibilidad con macOS/Ghidra más antiguos - local/manual: depuración de GUI específica del entorno más pesada y comprobaciones de cordura de lanzamiento ## API ### Herramientas Permite que los LLMs realicen acciones, hagan cálculos deterministas e interactúen con servicios externos. #### Operaciones por Lotes `decompile_function` y `list_xrefs` aceptan un solo objetivo o una lista de objetivos, reduciendo los viajes de ida y vuelta al analizar cadenas de llamadas o múltiples símbolos a la vez.```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"] }

#### Herramientas de Lectura / Análisis - `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)`: Busca pseudo-C descompilado mediante búsqueda vectorial semántica o coincidencia literal. - `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Lista referencias cruzadas a función(es), símbolo(s) o dirección(es). Acepta un solo objetivo o una lista para búsqueda por lotes. - `gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120)`: Genera un gráfico de llamadas MermaidJS para una función específica. Admite ambas direcciones "llamadas" (funciones llamadas por el objetivo) y "llamantes" (funciones que llaman al objetivo) con múltiples tipos de visualización. - `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)`: Descompila función(es) por nombre o dirección. Acepta un solo objetivo o una lista para descompilación por lotes. Los indicadores de respuesta enriquecida adjuntan callees, cadenas y/o referencias cruzadas a cada resultado. `timeout_sec` se aplica por objetivo y acota cada intento de descompilación de forma independiente. - `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lista todas las funciones y símbolos exportados de un binario específico (regex compatible para la consulta). - `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lista todas las funciones y símbolos importados de un binario específico (regex compatible para la consulta). - `read_bytes(binary_name: str, address: str, size: int = 32)`: Lee bytes sin procesar de la memoria en una dirección específica. Las direcciones hexadecimales pueden incluir u omitir el prefijo `0x`. - `search_strings(binary_name: str, query: str, limit: int = 100)`: Busca cadenas dentro de un binario. - `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Busca símbolos dentro de un binario por nombre. Admite patrones regex (p.ej., `^main$`, `func.*one`) con coincidencia sin distinción de mayúsculas, o consultas de subcadenas simples. Establece `functions_only=True` para excluir etiquetas, variables y otros símbolos que no sean funciones. #### Operaciones de Proyecto - `import_binary(binary_path: str)`: Importa un binario desde una ruta designada al proyecto actual de Ghidra. Si la ruta es un directorio, escaneará recursivamente e importará todos los archivos binarios compatibles, preservando la estructura de directorios dentro del proyecto de Ghidra. - `list_project_binaries()`: Lista los binarios en el proyecto actual de Ghidra. En modo GUI, esto incluye los binarios del proyecto que existen en disco incluso si no están abiertos actualmente en CodeBrowser. - `list_project_binary_metadata(binary_name: str)`: Recupera metadatos detallados de un binario específico, incluyendo arquitectura, compilador, formato ejecutable, métricas de análisis y hashes de archivos. - `delete_project_binary(binary_name: str)`: Elimina un binario (programa) del proyecto de Ghidra. #### Herramientas de Edición / Mutación - `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Renombra una función por nombre o dirección. En modo GUI, esto se ejecuta como una transacción en vivo de Ghidra y actualiza el programa abierto. - `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Renombra un parámetro de función o variable local por nombre exacto dentro de una función específica. Si el nombre falta o es ambiguo dentro de esa función, la herramienta devuelve un error en lugar de adivinar. En modo GUI, esto se ejecuta como una transacción en vivo de Ghidra y actualiza el programa abierto. - `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Establece el tipo de dato de un parámetro de función o variable local por nombre exacto dentro de una función específica. Si el nombre falta o es ambiguo dentro de esa función, la herramienta devuelve un error en lugar de adivinar. `type_name` se analiza usando el analizador de tipos de datos de Ghidra contra el gestor de tipos de datos del programa. - `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Establece un prototipo de función a partir de una cadena de firma completa. La herramienta siempre ejecuta el prototipo a través del analizador de firmas nativo de Ghidra y devuelve el error del analizador subyacente o de aplicación si el prototipo no es válido. - `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Establece un comentario de función/descompilador o comentario de lista. Los objetivos de comentarios de lista pueden ser direcciones, símbolos o funciones. Los valores admitidos de `comment_type` son `decompiler`, `plate`, `pre`, `eol`, `post` y `repeatable`. #### Herramientas de Control de GUI (`--gui` solo) Estas herramientas solo están disponibles cuando `pyghidra-mcp` se inicia con `--gui` y controlan lo que muestra la GUI en lugar de mutar los datos del proyecto directamente: - `list_open_programs()`: Lista los programas actualmente abiertos en la GUI de Ghidra. - `open_program_in_gui(binary_name: str, new_window: bool = True)`: Abre un binario del proyecto en CodeBrowser. Por defecto abre una nueva ventana de CodeBrowser. Establece `new_window=false` para reutilizar un CodeBrowser visible cuando sea posible. - `set_current_program(binary_name: str)`: Hace que un programa abierto sea el programa activo/actual en el contexto de la herramienta GUI principal. - `goto(binary_name: str, target: str, target_type: str)`: Navega la GUI de Ghidra a una dirección o función. `target_type` debe ser `address` o `function`. ## Uso Este paquete de Python se publica en PyPI como [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) y se puede instalar y ejecutar con [pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package), [pipx](https://pipx.pypa.io/), [uv](https://docs.astral.sh/uv/), [poetry](https://python-poetry.org/), o cualquier gestor de paquetes de 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.

Más Populares

pyghidra-mcp

Optimizado para Agentes

Cliente CLI

Instalación

Inicio rápido con CLI

Creación, Gestión y Apertura de Proyectos Existentes

Creación de Nuevos Proyectos

Estructura de Proyecto Autocontenida

Creación Básica de Proyectos```bash

Create a new project with default settings

Creates:

Creando múltiples proyectos relacionados```bash

Create separate projects for different analysis focuses

Project for suspicious binaries

Project for packed malware

Modo GUI

Mapeo de binarios con Docker

Create and populate the new directory

Run the Docker container with volume mapping

Con Docker

Docker

Eventos enviados por el servidor (SSE)

Python```bash

Integraciones

Claude Desktop