Python Ghidra MCP de línea de comandos
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/41597/82f9c5eb55db6134d47587275fce66c4ed32b86b5332f7e2d610fa0214070a7f.png" width=60% >
</p>
<p align="center">
<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/pyghidra-mcp/pytest-devcontainer-repo-all.yml?style=for-the-badge&label=pytest">
<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pyghidra-mcp?color=yellow&label=PyPI%20downloads&style=for-the-badge">
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/pyghidra-mcp?style=for-the-badge">
</p>
# PyGhidra-MCP - Servidor del Protocolo de Contexto de Modelo para Ghidra
### Descripción general
**`pyghidra-mcp`** es un servidor de línea de comandos del Protocolo de Contexto de Modelo (MCP) que lleva todo el poder analítico de [Ghidra](https://ghidra-sre.org/), una robusta suite de ingeniería inversa de software (SRE), al mundo de los agentes inteligentes y las herramientas basadas en LLM.
Conecta la [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) y la [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) de Ghidra con Python usando `pyghidra` y `jpype`, y luego expone esa funcionalidad a través del Protocolo de Contexto de Modelo.
MCP es una interfaz unificada que permite a los modelos de lenguaje, las herramientas de desarrollo (como VS Code) y los agentes autónomos acceder a contexto estructurado, invocar herramientas y colaborar de forma inteligente. Piense en MCP como el puente entre las potentes herramientas de análisis y el ecosistema de 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 admite dos modos de funcionamiento:
- modo `headless` para análisis y automatización dirigidos por CLI
- modo `--gui`, que lanza 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 sus comentarios, informes de errores, solicitudes de funciones y código.
## ¿Otro Ghidra MCP más?
Sí, el [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) original es fantástico. Pero `pyghidra-mcp` adopta un enfoque diferente:
- 🐍 **Headless-first, con capacidad de GUI** – Se ejecuta completamente a través de CLI para una automatización optimizada, o lanza Ghidra con `--gui` cuando desea navegación y edición en vivo mediante la GUI.
- 🔁 **Diseñado para la automatización** – Ideal para integrarse con LLM, pipelines de CI y herramientas que necesitan un comportamiento repetible.
- ✅ **Compatible con CI/CD** – Construido con sólidas pruebas unitarias y de integración tanto para sesiones de cliente como de servidor.
- 🚀 **Inicio rápido** – El inicio asíncrono permite que el servidor comience a gestionar solicitudes mientras los binarios aún se están analizando en segundo plano. Admite un lanzamiento rápido desde la línea de comandos con una configuración mínima.
- 📦 **Análisis de todo el proyecto** – Permite la ingeniería inversa concurrente de todos los binarios de 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 incrustaciones vectoriales (mediante ChromaDB) para permitir una búsqueda rápida y difusa en funciones descompiladas, comentarios y símbolos, perfecta para la exploración de pseudocódigo y el triaje dirigido por agentes.
Este proyecto ofrece una experiencia centrada en Python, optimizada para el desarrollo local, entornos headless 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["streamable HTTP (recommended)<br/>stdio (local fallback)"]
Tools["MCP tools"]
Context["PyGhidra context"]
end
Project["Ghidra project<br/>.gpr / .rep"]
Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]
Agent -->|"HTTP (recommended)"| Transport
Cli -->|"HTTP only"| Transport
Transport --> Tools
Tools --> Context
Context --> Project
Context --> Artifacts
Context -.-> Gui
User -.-> Gui
Gui -.-> Project
```
### Elegir un modo
```mermaid
flowchart TD
Start["What do you need?"]
Start --> Headless["Agent or automation"]
Start --> GuiNeed["Live Ghidra GUI control"]
Start --> Terminal["Interactive terminal client"]
Headless --> Http["pyghidra-mcp<br/>--transport streamable-http"]
GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]
```
- **MCP sin interfaz gráfica**: usa `streamable-http`. Mantiene Ghidra y su proyecto activos como un único servidor de larga duración y funciona tanto con hosts MCP como con el cliente CLI.
- **Modo GUI**: `pyghidra-mcp` inicia Ghidra, abre el proyecto y expone herramientas adicionales que controlan el CodeBrowser en la misma JVM.
- **Cliente CLI**: `pyghidra-mcp-cli` es un cliente HTTP. Inicia primero un servidor `streamable-http` y luego emite comandos de terminal contra ese servidor en ejecución.
- **stdio**: consérvalo solo para hosts MCP que no puedan conectarse a un endpoint HTTP.
<details>
<summary>Arquitectura detallada y superficie de herramientas</summary>
```mermaid
flowchart TD
subgraph Clients
Agent["LLM / MCP host"]
Cli["pyghidra-mcp-cli"]
Automation["scripts and CI"]
end
subgraph Transports
Stdio["stdio"]
Http["streamable-http"]
Sse["sse legacy"]
end
subgraph Server["pyghidra-mcp server"]
McpServer["MCPServer tool server"]
Context["PyGhidra context"]
Indexing["background analysis and Chroma indexing"]
subgraph Tools["MCP tools"]
Analysis["decompile, xrefs, bytes, callgraph"]
Search["symbols, strings, code"]
ProjectOps["import, delete, metadata, list binaries"]
Edits["rename function, rename variable, set type, set prototype, set comment"]
GuiOnly["GUI only: open program, goto, list open programs, set current program"]
end
end
subgraph GhidraRuntime["Ghidra runtime"]
PyGhidra["pyghidra"]
Jpype["JPype shared JVM"]
Project["Ghidra project"]
Programs["program databases"]
CodeBrowser["Ghidra GUI / CodeBrowser"]
end
Agent --> Http
Automation --> Http
Automation --> Sse
Cli --> Http
Stdio --> McpServer
Http --> McpServer
Sse --> McpServer
McpServer --> Context
Context --> PyGhidra
PyGhidra --> Jpype
Jpype --> Project
Project --> Programs
Context --> Indexing
Indexing --> Search
McpServer --> Tools
Tools --> Context
GuiOnly -.-> CodeBrowser
Context -.-> CodeBrowser
```
</details>
## Contenido
- [PyGhidra-MCP - Servidor del Protocolo de Contexto de Modelo de Ghidra](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Descripción general](#overview)
- [¿Otro MCP de Ghidra más?](#yet-another-ghidra-mcp)
- [Diagramas de configuración](#setup-diagrams)
- [Cómo se conectan las piezas](#how-the-pieces-connect)
- [Elección de 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)
- [Creación de 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 de 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 de GUI (solo `--gui`)](#gui-control-tools---gui-only)
- [Uso](#usage)
- [Mapeo de binarios con Docker](#mapping-binaries-with-docker)
- [HTTP transmitible](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Entrada/salida estándar (stdio)](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [Uso con OpenWeb-UI y MCPO](#using-with-openweb-ui-and-mcpo)
- [Con `uvx`](#with-uvx)
- [Con Docker](#docker-2)
- [Eventos enviados por el servidor (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Inspiración](#inspiration)
- [Contribución, comunidad y ejecución desde el código fuente](#contributing-community-and-running-from-source)
- [Flujo de trabajo del colaborador](#contributor-workflow)
## Primeros pasos
Inicie un servidor HTTP transmitible persistente utilizando el [paquete de Python](https://pypi.org/p/pyghidra-mcp) y [`uv`](https://docs.astral.sh/uv/guides/tools/):
```bash
uvx pyghidra-mcp \
--transport streamable-http \
--project-path /absolute/path/to/ghidra-projects \
/absolute/path/to/binary
```
El servidor está entonces disponible en `http://127.0.0.1:8000/mcp`. Déjalo en ejecución y configura tu cliente MCP para usar esa URL; los ejemplos de [Claude Code](#claude-code) y [Codex](#codex) a continuación muestran la configuración esperada.
Para lanzar y controlar una GUI de Ghidra en vivo desde MCP, usa `--gui` con `streamable-http`:
```bash
uvx pyghidra-mcp \
--gui \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--project-path /absolute/path/to/ghidra-projects \
--project-name my_project
```
> [!IMPORTANT]
> `--gui` lanza Ghidra a través de `pyghidra-mcp`. No se conecta a una instancia de Ghidra externa que ya esté en ejecución.
O bien, ejecútalo como un [contenedor Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Optimizado para agentes
`pyghidra-mcp` mantiene la superficie MCP intencionalmente reducida para que los clientes de agentes gasten menos tokens en el descubrimiento de herramientas y la selección de argumentos.
- **Descripciones breves de herramientas**: los docstrings de las herramientas MCP se mantienen compactos para que los esquemas de herramientas de MCPServer sigan siendo pequeños y económicos de enviar a los modelos.
- **Disciplina de contexto**: las herramientas devuelven datos estructurados y enfocados en lugar de volcar el contexto de todo el programa por defecto. Los resultados de descompilación, búsqueda de símbolos y referencias cruzadas están diseñados para apoyar el análisis iterativo en lugar de una única respuesta grande.
- **Herramientas de GUI solo cuando son relevantes**: los controles exclusivos de GUI como `open_program_in_gui`, `list_open_programs`, `set_current_program` y `goto` solo se exponen cuando el servidor se inicia con `--gui`.
- **CLI es opcional**: si MCP no es tu interfaz preferida, `pyghidra-mcp-cli` proporciona un cliente de línea de comandos directo sobre HTTP con comandos agrupados para flujos de trabajo comunes de edición y análisis.
Esto mantiene el servidor por defecto utilizable para agentes LLM, integraciones de IDE y automatización sin exponer una superficie de herramientas innecesaria ni controles exclusivos de GUI en sesiones sin interfaz gráfica.
## Cliente CLI
Para una experiencia de línea de comandos más interactiva, puedes usar el paquete separado **pyghidra-mcp-cli**, que proporciona una interfaz fácil de usar para interactuar con un servidor pyghidra-mcp en ejecución.
### Instalación
Instala el cliente CLI usando [`uv`](https://docs.astral.sh/uv/) (recomendado):
```bash
uvx pyghidra-mcp-cli
```
O instalar con pip:
```bash
pip install pyghidra-mcp-cli
```
### Inicio rápido con la CLI
1. **Iniciar el servidor** (en una terminal):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **Usar 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
```
> [!NOTE]
> La CLI se conecta a pyghidra-mcp mediante HTTP para evitar la sobrecarga de inicio de 10-60 segundos que supone lanzar un nuevo proceso de Ghidra para cada comando. Consulte el [README de la CLI](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) para obtener documentación completa.
## Creación de proyectos, gestión y apertura de proyectos existentes
### Creación de nuevos proyectos
Puede crear nuevos proyectos de varias formas, según su flujo de trabajo:
#### Estructura de proyecto autocontenida
`pyghidra-mcp` crea una **estructura de proyecto autocontenida** en la que cada proyecto tiene su propio proyecto de Ghidra y sus propios artefactos de pyghidra-mcp. Esto garantiza un aislamiento completo y una gestión sencilla de los proyectos.
#### Creación básica de proyectos
```bash
# Create a new project with default settings
pyghidra-mcp
# Creates:
$ tree pyghidra_mcp_projects/
pyghidra_mcp_projects/
├── my_project.gpr
├── my_project-pyghidra-mcp
│ ├── chromadb
│ └── gzfs
└── my_project.rep
```
#### 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
```
#### Creación de múltiples proyectos relacionados
```bash
# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace
# Project for suspicious binaries
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis
# Project for packed malware
pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis
```
### Abrir proyectos de Ghidra existentes
Si tienes proyectos de Ghidra existentes (archivos `.gpr`), puedes abrirlos directamente con `pyghidra-mcp`:
#### Abrir mediante 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)
```
### Modo GUI
Utilice el modo GUI cuando desee que las acciones de MCP operen sobre los mismos objetos de programa en vivo que Ghidra está mostrando.
- `--gui` requiere `--transport streamable-http` (o `--transport http` como alias)
- `--project-path` puede ser un directorio de proyecto más `--project-name`, o un archivo `.gpr` existente. Los proyectos faltantes se crean automáticamente.
- Ghidra es lanzado por `pyghidra-mcp`, lo que mantiene las transacciones de GUI y MCP en la misma JVM
- Las herramientas exclusivas de GUI solo se exponen cuando se ejecuta con `--gui`
Ejemplo:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
El modo GUI es la opción correcta cuando quieres:
- abrir o cambiar programas en CodeBrowser
- navegar el listado hasta una función o dirección
- renombrar funciones o añadir comentarios y ver esos cambios inmediatamente en Ghidra
### Valores predeterminados de inicio y proyectos grandes
`pyghidra-mcp` no requiere `--wait-for-analysis` de forma predeterminada. El servidor puede iniciarse 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 arranque del servidor
- `--wait-for-analysis` está disponible cuando quieres un proyecto completamente analizado antes de atender solicitudes
- para proyectos grandes existentes, es de esperar que la preparación del análisis y la indexación varíe según el binario
Limitación actual:
- el estado del análisis de Ghidra y el estado de indexación de MCP son independientes
- un binario puede estar completamente analizado en Ghidra mientras `search_strings` o la búsqueda semántica `search_code` siguen esperando la indexación del lado de MCP
- esto es más notable al abrir proyectos grandes existentes
En la práctica:
- la descompilación, la navegación, el renombrado y los comentarios pueden seguir funcionando para un binario mientras las funciones de búsqueda con mucha indexación se ponen al día
- si la latencia de inicio importa más que la disponibilidad inmediata de búsqueda, mantén el valor predeterminado `--no-wait-for-analysis`
- si la disponibilidad inmediata importa más que el tiempo de inicio, usa `--wait-for-analysis`
## Desarrollo
Este proyecto usa un `Makefile` para agilizar el desarrollo y las pruebas. `ruff` se usa para linting y formateo, y los hooks de `pre-commit` se usan 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 bien, 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 el 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/main/: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 usada 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`: Comprobar el estilo del código con `ruff`.
- `make format`: Formatear el 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 (formateo y comprobación).
- `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 headless en Linux, GUI de Linux bajo `Xvfb`, cobertura de CLI y pruebas de humo actuales en macOS
- CI programado: cobertura de compatibilidad con versiones anteriores de macOS / Ghidra
- local/manual: depuración de GUI más pesada específica del entorno y comprobaciones de sanidad de la versión
## API
### Herramientas
Permiten a los LLM realizar acciones, hacer cálculos deterministas e interactuar con servicios externos.
#### Operaciones por lotes
`decompile_function` y `list_xrefs` aceptan un único objetivo o una lista de objetivos, lo que reduce 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"]
}
```
Los errores por elemento se devuelven en línea (los demás objetivos siguen teniendo éxito):
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### 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 en pseudo-C descompilado usando búsqueda vectorial semántica o coincidencia literal.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Lista las referencias cruzadas a función(es), símbolo(s) o dirección(es). Acepta un único 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 grafo de llamadas MermaidJS para una función especificada. Admite las direcciones "calling" (funciones llamadas por el objetivo) y "called" (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 único objetivo o una lista para descompilación por lotes. Los indicadores de respuesta enriquecida adjuntan callees, strings y/o xrefs a cada resultado. `timeout_sec` se aplica por objetivo y limita 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 especificado (se admite regex 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 especificado (se admite regex para la consulta).
- `read_bytes(binary_name: str, address: str, size: int = 32)`: Lee bytes sin procesar de la memoria en una dirección especificada. Las direcciones hexadecimales pueden incluir u omitir el prefijo `0x`.
- `search_strings(binary_name: str, query: str, limit: int = 100)`: Busca strings 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 y minúsculas, o consultas de subcadena simples. Establezca `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 Ghidra actual. Si la ruta es un directorio, escaneará e importará recursivamente todos los archivos binarios compatibles, preservando la estructura de directorios dentro del proyecto Ghidra.
- `list_project_binaries()`: Lista los binarios en el proyecto Ghidra actual. En modo GUI esto incluye 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 archivo.
- `delete_project_binary(binary_name: str)`: Elimina un binario (programa) del proyecto 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 para 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 dato de Ghidra contra el gestor de tipos de dato 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 pasa el prototipo por el analizador de firmas nativo de Ghidra y devuelve el error subyacente del analizador 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 un comentario de listado. Los objetivos de comentario de listado 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 (solo `--gui`)
Estas herramientas solo están disponibles cuando `pyghidra-mcp` se inicia con `--gui` y controlan lo que muestra la GUI en lugar de mutar directamente los datos del proyecto:
- `list_open_programs()`: Lista los programas abiertos actualmente 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 esto abre una nueva ventana de CodeBrowser. Establezca `new_window=false` para reutilizar un CodeBrowser visible cuando sea posible.
- `set_current_program(binary_name: str)`: Convierte un programa abierto en el programa activo/actual en el contexto principal de la herramienta GUI.
- `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 está publicado 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.
```
### Asignación de binarios con Docker
Al usar el contenedor Docker, puedes asignar un directorio local que contenga tus binarios al espacio de trabajo del contenedor. Esto permite que `pyghidra-mcp` analice tus archivos.
```bash
# Create and populate the new directory
mkdir -p ./binaries
cp /path/to/your/binaries/* ./binaries/
# Run the Docker container with volume mapping
docker run -i --rm \
-v "$(pwd)/binaries:/binaries" \
ghcr.io/clearbluejar/pyghidra-mcp \
/binaries/*
```
### Streamable HTTP
Streamable HTTP es el transporte recomendado. Mantiene un proceso de Ghidra y un proyecto disponibles para los hosts de MCP y `pyghidra-mcp-cli`, evitando el coste de inicio de un proceso separado por cliente. Envía solicitudes JSON-RPC a través de HTTP; consulta la [especificación](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) para más detalles.
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)