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

> [!IMPORTANT]
> `--gui` inicia Ghidra a través de `pyghidra-mcp`. No se adjunta a una instancia externa de Ghidra ya en ejecución.

O, ejecútelo como un [contenedor Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):```bash
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

O instalar con pip:```bash
pip install pyghidra-mcp-cli

2. **Usa la CLI** (en otra terminal):```bash
# List available binaries
pyghidra-mcp-cli list binaries

# Decompile a function
pyghidra-mcp-cli decompile --binary ls main

# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs

# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10

#### Creación de Proyecto Personalizado```bash
# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis

$ tree ~/analysis/ 
/home/vscode/analysis/
└── malware_study
    ├── malware_analysis.gpr
    ├── malware_analysis-pyghidra-mcp
    │   ├── chromadb
    │   └── gzfs
    └── malware_analysis.rep

### Abriendo proyectos existentes de Ghidra

Si tienes proyectos existentes de Ghidra (archivos `.gpr`), puedes abrirlos directamente con `pyghidra-mcp`:

#### Abriendo por archivo .gpr```bash
# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr

# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)

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.

### Usando con OpenWeb-UI y MCPO

Puedes integrar `pyghidra-mcp` con [OpenWeb-UI](https://github.com/open-webui/open-webui) usando [MCPO](https://github.com/open-webui/mcpo), un proxy de MCP a OpenAPI. Esto te permite exponer las herramientas de `pyghidra-mcp` a través de una API RESTful estándar, haciéndolas accesibles para interfaces web y otras herramientas.


https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95


#### Con `uvx`

Puedes ejecutar `pyghidra-mcp` y `mcpo` juntos usando `uvx`:```bash
uvx mcpo -- \
  pyghidra-mcp /bin/ls

### Entrada/Salida Estándar (stdio)

El transporte stdio permite la comunicación a través de flujos de entrada y salida estándar. Esto es particularmente útil para integraciones locales y herramientas de línea de comandos. Consulte la [especificación](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) para más detalles.

#### Python```bash
pyghidra-mcp

Por defecto, el contenedor Docker inicia el servidor `streamable-http`, así que incluya `-t stdio` después del nombre de la imagen y ejecute con `-i` para el modo stdio [interactivo](https://docs.docker.com/reference/cli/docker/container/run/#interactive).

### Streamable HTTP

Streamable HTTP permite respuestas en streaming sobre JSON RPC a través de solicitudes HTTP POST. Consulte la [especificación](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) para más detalles.

Por defecto, el servidor escucha en [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) para conexiones de clientes. Use `--host` / `--port` o las variables de entorno `MCP_HOST` / `MCP_PORT` para cambiar la dirección de enlace. _El servidor debe estar en ejecución para que los clientes se conecten a él._

#### Python```bash
pyghidra-mcp -t streamable-http

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

Por defecto, el paquete de Python se ejecutará en modo `stdio`, por lo que tendrás que incluir `-t sse`.

#### Docker```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

## Inspiración

La implementación y diseño de este proyecto se inspiraron en estos proyectos increíbles:

* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
* [semgrep-mcp](https://github.com/semgrep/mcp)
* [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)
* [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)

---

## Contribuir, comunidad y ejecución desde el código fuente

Creemos que el futuro de la ingeniería inversa es agentivo, contextual y escalable.  
`pyghidra-mcp` es un paso hacia ese futuro—hacer que los proyectos completos de Ghidra sean accesibles para agentes de IA y pipelines de automatización.

Estamos desarrollando activamente el proyecto y agradecemos comentarios, problemas y contribuciones.

> [!NOTE]
> Nos encantan sus comentarios, informes de errores, solicitudes de funciones y código.

### Flujo de trabajo del colaborador

Si estás añadiendo una nueva herramienta o integración, este es el flujo de trabajo recomendado:

- Etiqueta tu rama con el prefijo `feature/` para indicar una nueva capacidad.
- Añade tu herramienta usando el mismo estilo y estructura que las herramientas existentes en `pyghidra/tools/`.
- Escribe una prueba de integración que ejercite tu herramienta usando una instancia de `StdioClient`. Colócala en `tests/integration/`.
- Amplía las pruebas concurrentes añadiendo una llamada a tu herramienta en `tests/integration/test_concurrent_streamable_client.py`.
- Ejecuta `make test` y `make format` para asegurarte de que tus cambios pasan todas las pruebas y cumplen con las reglas de linting.

Esto asegura consistencia en todo el código base y nos ayuda a mantener herramientas robustas y escalables para flujos de trabajo de ingeniería inversa.

______________________________________________________________________

Hecho con ❤️ por el [PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp)