Ghidra MCP de Linha de Comando em Python
<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 Ghidra Model Context Protocol
### Visão Geral
**`pyghidra-mcp`** é um servidor de linha de comando Model Context Protocol (MCP) que traz todo o poder analítico do [Ghidra](https://ghidra-sre.org/), uma robusta suíte de engenharia reversa de software (SRE), para o mundo dos agentes inteligentes e ferramentas baseadas em LLM.
Ele faz a ponte entre a [ProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/model/listing/Program.html) e a [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) do Ghidra para Python usando `pyghidra` e `jpype`, e então expõe essa funcionalidade através do Model Context Protocol.
MCP é uma interface unificada que permite que modelos de linguagem, ferramentas de desenvolvimento (como o VS Code) e agentes autônomos acessem contexto estruturado, invoquem ferramentas e colaborem de forma inteligente. Pense no MCP como a ponte entre ferramentas de análise poderosas e o ecossistema de LLMs.
Com o `pyghidra-mcp`, o Ghidra se torna um backend inteligente — pronto para responder a consultas ricas em contexto, automatizar tarefas profundas de engenharia reversa e se integrar a fluxos de trabalho assistidos por IA.
O `pyghidra-mcp` agora suporta dois modos de operação:
- modo `headless` para análise e automação via CLI
- modo `--gui`, que inicia o Ghidra através do `pyghidra-mcp` e compartilha o estado do programa em tempo real com a GUI em execução
> [!NOTE]
> Este projeto beta está em desenvolvimento ativo. Adoraríamos receber seu feedback, relatórios de bugs, solicitações de recursos e código.
## Mais um Ghidra MCP?
Sim, o [ghidra-mcp](https://github.com/LaurieWired/GhidraMCP) original é fantástico. Mas o `pyghidra-mcp` adota uma abordagem diferente:
- 🐍 **Headless-first, com suporte a GUI** – Execute inteiramente via CLI para automação simplificada, ou inicie o Ghidra com `--gui` quando quiser navegação e edições ao vivo na GUI.
- 🔁 **Projetado para automação** – Ideal para integração com LLMs, pipelines de CI e ferramentas que precisam de comportamento repetível.
- ✅ **Compatível com CI/CD** – Construído com testes unitários e de integração robustos tanto para sessões de cliente quanto de servidor.
- 🚀 **Inicialização rápida** – A inicialização assíncrona permite que o servidor comece a lidar com requisições enquanto os binários ainda estão sendo analisados em segundo plano. Suporta inicialização rápida pela linha de comando com configuração mínima.
- 📦 **Análise de todo o projeto** – Permite engenharia reversa concorrente de todos os binários em um projeto Ghidra
- 🤖 **Pronto para agentes** – Construído para fluxos de trabalho inteligentes orientados por agentes e automação de engenharia reversa em larga escala.
- 🔍 Busca semântica de código – Usa embeddings vetoriais (via ChromaDB) para permitir busca rápida e difusa em funções descompiladas, comentários e símbolos — perfeito para exploração de pseudo-C e triagem orientada por agentes.
Este projeto oferece uma experiência Python-first otimizada para desenvolvimento local, ambientes headless e fluxos de trabalho testáveis.
## Diagramas de Configuração
### Como as Peças se Conectam
```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
```
### Escolhendo um 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 Headless**: use `streamable-http`. Ele mantém o Ghidra e seu projeto vivos como um servidor de longa duração e funciona tanto com hosts MCP quanto com o cliente CLI.
- **Modo GUI**: `pyghidra-mcp` inicia o Ghidra, abre o projeto e expõe ferramentas extras que controlam o CodeBrowser na mesma JVM.
- **Cliente CLI**: `pyghidra-mcp-cli` é um cliente HTTP. Inicie primeiro um servidor `streamable-http` e depois emita comandos de terminal contra esse servidor em execução.
- **stdio**: mantenha isto apenas para hosts MCP que não conseguem conectar-se a um endpoint HTTP.
<details>
<summary>Arquitetura detalhada e superfície de ferramentas</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>
## Conteúdo
- [PyGhidra-MCP - Servidor do Protocolo de Contexto de Modelo do Ghidra](#pyghidra-mcp---ghidra-model-context-protocol-server)
- [Visão Geral](#overview)
- [Mais um Ghidra MCP?](#yet-another-ghidra-mcp)
- [Diagramas de Configuração](#setup-diagrams)
- [Como as Peças se Conectam](#how-the-pieces-connect)
- [Escolhendo um Modo](#choosing-a-mode)
- [Conteúdo](#contents)
- [Primeiros Passos](#getting-started)
- [Otimizado para Agentes](#optimized-for-agents)
- [Cliente CLI](#cli-client)
- [Instalação](#installation)
- [Início Rápido com CLI](#quick-start-with-cli)
- [Criação, Gerenciamento e Abertura de Projetos Existentes](#project-creation-management-and-opening-existing-projects)
- [Criando Novos Projetos](#creating-new-projects)
- [Estrutura de Projeto Autocontida](#self-contained-project-structure)
- [Criação Básica de Projeto](#basic-project-creation)
- [Criação Personalizada de Projeto](#custom-project-creation)
- [Criando Múltiplos Projetos Relacionados](#creating-multiple-related-projects)
- [Abrindo Projetos Ghidra Existentes](#opening-existing-ghidra-projects)
- [Abrindo por Arquivo .gpr](#opening-by-gpr-file)
- [Modo GUI](#gui-mode)
- [Padrões de Inicialização e Projetos Grandes](#startup-defaults-and-large-projects)
- [Desenvolvimento](#development)
- [Configuração](#setup)
- [Testes e Qualidade](#testing-and-quality)
- [API](#api)
- [Ferramentas](#tools)
- [Operações em Lote](#batch-operations)
- [Ferramentas de Leitura / Análise](#read--analysis-tools)
- [Operações de Projeto](#project-operations)
- [Ferramentas de Edição / Mutação](#edit--mutation-tools)
- [Ferramentas de Controle da GUI (apenas `--gui`)](#gui-control-tools---gui-only)
- [Uso](#usage)
- [Mapeando Binários com Docker](#mapping-binaries-with-docker)
- [HTTP Transmissível](#streamable-http)
- [Python](#python)
- [Docker](#docker)
- [Claude Code](#claude-code)
- [Codex](#codex)
- [Entrada/Saída Padrão (stdio)](#standard-inputoutput-stdio)
- [Python](#python-1)
- [Docker](#docker-1)
- [Usando com OpenWeb-UI e MCPO](#using-with-openweb-ui-and-mcpo)
- [Com `uvx`](#with-uvx)
- [Com Docker](#docker-2)
- [Eventos enviados pelo servidor (SSE)](#server-sent-events-sse)
- [Python](#python-2)
- [Docker](#docker-3)
- [Inspiração](#inspiration)
- [Contribuição, comunidade e execução a partir do código-fonte](#contributing-community-and-running-from-source)
- [Fluxo de trabalho do contribuidor](#contributor-workflow)
## Primeiros Passos
Inicie um servidor HTTP Transmissível persistente usando o [pacote Python](https://pypi.org/p/pyghidra-mcp) e o [`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
```
O servidor fica então disponível em `http://127.0.0.1:8000/mcp`. Deixe-o em execução e configure o seu cliente MCP para usar esse URL; os exemplos de [Claude Code](#claude-code) e [Codex](#codex) abaixo mostram a configuração esperada.
Para iniciar e controlar uma GUI do Ghidra em execução a partir do MCP, use `--gui` com `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` inicia o Ghidra através do `pyghidra-mcp`. Ele não se conecta a uma instância externa do Ghidra já em execução.
Ou, execute como um [contêiner Docker](https://ghcr.io/clearbluejar/pyghidra-mcp):
```bash
docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
## Otimizado para Agentes
`pyghidra-mcp` mantém a superfície MCP intencionalmente restrita para que os clientes de agentes gastem menos tokens na descoberta de ferramentas e na seleção de argumentos.
- **Descrições curtas de ferramentas**: As docstrings das ferramentas MCP são mantidas compactas para que os esquemas de ferramentas do MCPServer permaneçam pequenos e baratos de enviar aos modelos.
- **Disciplina de contexto**: as ferramentas retornam dados estruturados focados em vez de despejar o contexto do programa inteiro por padrão. Resultados de descompilação, busca de símbolos e referências cruzadas são moldados para apoiar análise iterativa em vez de uma única resposta grande.
- **Ferramentas de GUI apenas quando relevante**: controles exclusivos de GUI como `open_program_in_gui`, `list_open_programs`, `set_current_program` e `goto` só são expostos quando o servidor é iniciado com `--gui`.
- **CLI é opcional**: se MCP não é sua interface preferida, `pyghidra-mcp-cli` fornece um cliente de linha de comando direto sobre HTTP com comandos agrupados para fluxos de trabalho comuns de edição e análise.
Isso mantém o servidor padrão utilizável para agentes LLM, integrações de IDE e automação sem expor superfície de ferramentas desnecessária ou controles exclusivos de GUI em sessões headless.
## Cliente CLI
Para uma experiência de linha de comando mais interativa, você pode usar o pacote separado **pyghidra-mcp-cli**, que fornece uma interface amigável para interagir com um servidor pyghidra-mcp em execução.
### Instalação
Instale o cliente CLI usando [`uv`](https://docs.astral.sh/uv/) (recomendado):
```bash
uvx pyghidra-mcp-cli
```
Ou instale com pip:
```bash
pip install pyghidra-mcp-cli
```
### Início Rápido com CLI
1. **Inicie o servidor** (em um terminal):
```bash
pyghidra-mcp --transport streamable-http /bin/ls
```
2. **Use a CLI** (em outro 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]
> A CLI se conecta ao pyghidra-mcp via HTTP para evitar a sobrecarga de inicialização de 10-60 segundos ao gerar um novo processo Ghidra para cada comando. Consulte o [CLI README](https://github.com/clearbluejar/pyghidra-mcp/blob/main/cli/README.md) para documentação completa.
## Criação, Gerenciamento e Abertura de Projetos Existentes
### Criando Novos Projetos
Você pode criar novos projetos de várias maneiras, dependendo do seu fluxo de trabalho:
#### Estrutura de Projeto Autocontida
`pyghidra-mcp` cria uma **estrutura de projeto autocontida** onde cada projeto tem seu próprio projeto Ghidra e artefatos pyghidra-mcp. Isso garante isolamento completo e gerenciamento fácil de projetos.
#### Criação Básica de Projeto
```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
```
#### Criação de Projeto 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
```
#### Criando Múltiplos Projetos 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
```
### Abrindo Projetos Ghidra Existentes
Se você tem projetos Ghidra existentes (arquivos `.gpr`), você pode abri-los diretamente com `pyghidra-mcp`:
#### Abrindo por Arquivo .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
Use o modo GUI quando quiser que as ações do MCP operem sobre os mesmos objetos de programa ativos que o Ghidra está exibindo.
- `--gui` requer `--transport streamable-http` (ou `--transport http` como alias)
- `--project-path` pode ser um diretório de projeto mais `--project-name`, ou um arquivo `.gpr` existente. Projetos ausentes são criados automaticamente.
- O Ghidra é iniciado pelo `pyghidra-mcp`, que mantém as transações da GUI e do MCP na mesma JVM
- Ferramentas exclusivas da GUI só são expostas quando executadas com `--gui`
Exemplo:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_research.gpr
```
O modo GUI é a escolha certa quando você quer:
- abrir ou alternar programas no CodeBrowser
- navegar na listagem até uma função ou endereço
- renomear funções ou adicionar comentários e ver essas alterações imediatamente no Ghidra
### Padrões de Inicialização e Projetos Grandes
O `pyghidra-mcp` não requer `--wait-for-analysis` por padrão. O servidor pode iniciar enquanto a análise e a indexação do lado do MCP continuam em segundo plano.
Isso é importante para projetos grandes:
- iniciar um projeto com muitos binários não precisa bloquear a inicialização do servidor
- `--wait-for-analysis` está disponível quando você quer um projeto totalmente analisado antes de atender requisições
- para projetos grandes existentes, espere que a prontidão da análise e da indexação varie por binário
Limitação atual:
- o estado da análise do Ghidra e o estado da indexação do MCP são separados
- um binário pode estar totalmente analisado no Ghidra enquanto `search_strings` ou `search_code` semântico ainda estão aguardando a indexação do lado do MCP
- isso é mais perceptível ao abrir projetos grandes existentes
Na prática:
- descompilação, navegação, renomeação e comentários ainda podem funcionar para um binário enquanto os recursos de busca com indexação pesada estão se atualizando
- se a latência de inicialização importa mais do que a prontidão imediata da busca, mantenha o padrão `--no-wait-for-analysis`
- se a prontidão imediata importa mais do que o tempo de inicialização, use `--wait-for-analysis`
## Desenvolvimento
Este projeto usa um `Makefile` para simplificar o desenvolvimento e os testes. `ruff` é usado para linting e formatação, e hooks de `pre-commit` são usados para garantir a qualidade do código.
### Configuração
1. **Instale o `uv`**: Se você não tem o `uv` instalado, pode instalá-lo usando pip:
```bash
pip install uv
```
Ou siga o guia oficial de instalação do `uv`: [https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)
2. **Crie um ambiente virtual e instale as dependências**:
```bash
make dev-setup
source ./.venv/bin/activate
```
3. **Defina a Variável de Ambiente do Ghidra**: Baixe e instale o Ghidra, depois defina a variável de ambiente `GHIDRA_INSTALL_DIR` para o diretório de instalação do 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)
```
### Testes e Qualidade
O `Makefile` fornece vários alvos para testes e qualidade de código:
- `make run`: Executa o servidor MCP.
- `make test`: Executa a suíte de testes completa (unitários e de integração).
- `make test-unit`: Executa os testes unitários.
- `make test-integration`: Executa os testes de integração.
- `make test-integration-fast`: Executa o teste de fumaça de integração leve usado pelo pre-commit.
- `make test-integration-gui`: Executa os testes de integração de GUI. Requer uma instalação funcional do Ghidra e suporte a GUI.
- `make lint`: Verifica o estilo do código com `ruff`.
- `make format`: Formata o código com `ruff`.
- `make typecheck`: Executa verificações estáticas leves com `ruff`.
- `make check`: Executa todas as verificações de qualidade.
- `make dev`: Executa o fluxo de trabalho de desenvolvimento (formatação e verificação).
- `make build`: Compila os pacotes de distribuição.
- `make clean`: Limpa os artefatos de build e o cache.
Divisão recomendada:
- pre-commit: `ruff`, `pyright`, testes unitários e um teste de fumaça de integração leve
- GitHub Actions: cobertura completa de integração headless no Linux, GUI no Linux sob `Xvfb`, cobertura de CLI e testes de fumaça atuais no macOS
- CI agendado: cobertura de compatibilidade com versões mais antigas de macOS / Ghidra
- local/manual: depuração de GUI mais pesada específica do ambiente e verificações de sanidade de release
## API
### Ferramentas
Permitem que LLMs executem ações, façam computações determinísticas e interajam com serviços externos.
#### Operações em Lote
`decompile_function` e `list_xrefs` aceitam um único alvo ou uma lista de alvos, reduzindo round-trips ao analisar cadeias de chamadas ou múltiplos símbolos de uma 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"]
}
```
Erros por item são retornados inline (os outros alvos ainda são bem-sucedidos):
```jsonc
[
{"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
{"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]
```
#### Ferramentas de Leitura / Análise
- `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)`: Pesquisa pseudo-C descompilado usando busca vetorial semântica ou correspondência literal.
- `list_xrefs(binary_name: str, name_or_address: str | list[str])`: Lista referências cruzadas para função(ões), símbolo(s) ou endereço(s). Aceita um único alvo ou uma lista para consulta em lote.
- `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)`: Gera um grafo de chamadas MermaidJS para uma função especificada. Suporta ambas as direções "calling" (funções chamadas pelo alvo) e "called" (funções que chamam o alvo) com múltiplos tipos de visualização.
- `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 função(ões) por nome ou endereço. Aceita um único alvo ou uma lista para descompilação em lote. Flags de resposta enriquecida anexam callees, strings e/ou xrefs a cada resultado. `timeout_sec` aplica-se por alvo e limita cada tentativa de descompilação independentemente.
- `list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lista todas as funções e símbolos exportados de um binário especificado (regex suportado para query).
- `list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)`: Lista todas as funções e símbolos importados de um binário especificado (regex suportado para query).
- `read_bytes(binary_name: str, address: str, size: int = 32)`: Lê bytes brutos da memória em um endereço especificado. Endereços hexadecimais podem incluir ou omitir o prefixo `0x`.
- `search_strings(binary_name: str, query: str, limit: int = 100)`: Pesquisa strings dentro de um binário.
- `search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25)`: Pesquisa símbolos dentro de um binário por nome. Suporta padrões regex (ex.: `^main$`, `func.*one`) com correspondência case-insensitive, ou consultas de substring simples. Defina `functions_only=True` para excluir labels, variáveis e outros símbolos que não são funções.
#### Operações de Projeto
- `import_binary(binary_path: str)`: Importa um binário de um caminho designado para o projeto Ghidra atual. Se o caminho for um diretório, ele escaneará recursivamente e importará todos os arquivos binários suportados, preservando a estrutura de diretórios dentro do projeto Ghidra.
- `list_project_binaries()`: Lista binários no projeto Ghidra atual. No modo GUI, isso inclui binários do projeto que existem no disco mesmo que não estejam atualmente abertos no CodeBrowser.
- `list_project_binary_metadata(binary_name: str)`: Recupera metadados detalhados para um binário específico, incluindo arquitetura, compilador, formato executável, métricas de análise e hashes de arquivo.
- `delete_project_binary(binary_name: str)`: Exclui um binário (programa) do projeto Ghidra.
#### Ferramentas de Edição / Mutação
- `rename_function(binary_name: str, name_or_address: str, new_name: str)`: Renomeia uma função por nome ou endereço. No modo GUI, isso é executado como uma transação Ghidra ao vivo e atualiza o programa aberto.
- `rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str)`: Renomeia um parâmetro de função ou variável local por nome exato dentro de uma função específica. Se o nome estiver ausente ou ambíguo dentro dessa função, a ferramenta retorna um erro em vez de adivinhar. No modo GUI, isso é executado como uma transação Ghidra ao vivo e atualiza o programa aberto.
- `set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str)`: Define o tipo de dado para um parâmetro de função ou variável local por nome exato dentro de uma função específica. Se o nome estiver ausente ou ambíguo dentro dessa função, a ferramenta retorna um erro em vez de adivinhar. `type_name` é analisado usando o parser de datatype do Ghidra contra o gerenciador de datatype do programa.
- `set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str)`: Define um protótipo de função a partir de uma string de assinatura completa. A ferramenta sempre executa o protótipo através do parser de assinatura nativo do Ghidra e retorna o erro subjacente do parser ou de aplicação se o protótipo for inválido.
- `set_comment(binary_name: str, target: str, comment: str, comment_type: str)`: Define um comentário de função/descompilador ou comentário de listagem. Alvos de comentário de listagem podem ser endereços, símbolos ou funções. Os valores suportados de `comment_type` são `decompiler`, `plate`, `pre`, `eol`, `post` e `repeatable`.
#### Ferramentas de Controle da GUI (apenas `--gui`)
Estas ferramentas estão disponíveis apenas quando `pyghidra-mcp` é iniciado com `--gui` e controlam o que a GUI está exibindo em vez de mutar diretamente os dados do projeto:
- `list_open_programs()`: Lista programas atualmente abertos na GUI do Ghidra.
- `open_program_in_gui(binary_name: str, new_window: bool = True)`: Abre um binário do projeto no CodeBrowser. Por padrão, isso abre uma nova janela do CodeBrowser. Defina `new_window=false` para reutilizar um CodeBrowser visível quando possível.
- `set_current_program(binary_name: str)`: Torna um programa aberto o programa ativo/atual no contexto principal da ferramenta GUI.
- `goto(binary_name: str, target: str, target_type: str)`: Navega a GUI do Ghidra para um endereço ou função. `target_type` deve ser `address` ou `function`.
## Uso
Este pacote Python é publicado no PyPI como [pyghidra-mcp](https://pypi.org/p/pyghidra-mcp) e pode ser instalado e executado com [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 qualquer gerenciador de pacotes 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.
```
### Mapeando Binários com Docker
Ao usar o contêiner Docker, você pode mapear um diretório local contendo seus binários para o workspace do contêiner. Isso permite que o `pyghidra-mcp` analise seus arquivos.
```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 é o transporte recomendado. Ele mantém um processo Ghidra e um projeto disponíveis para hosts MCP e `pyghidra-mcp-cli`, evitando o custo de inicialização de um processo separado por cliente. Ele envia requisições JSON-RPC via HTTP; consulte a [spec](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) para detalhes.
Por padrão, o servidor escuta em [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) para conexões de clientes. Use `--host` / `--port` ou as variáveis de ambiente `MCP_HOST` / `MCP_PORT` para alterar o endereço de bind. _O servidor deve estar em execução para que os clientes possam se conectar a ele._
#### Python
```bash
pyghidra-mcp -t streamable-http
```
O pacote Python usa `stdio` por padrão, portanto sempre inclua `--transport streamable-http` ao iniciar o servidor.
O modo GUI usa este transporte:
```bash
pyghidra-mcp \
--gui \
--transport streamable-http \
--project-path /absolute/path/to/my_project.gpr
```
#### Docker
```
docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp
```
### Claude Code
---
[Read more](https://github.com/clearbluejar/pyghidra-mcp)