Servidor Ghidra MCP

Se você achar isso útil, por favor ⭐ dê uma estrela no repositório — isso ajuda outras pessoas a descobri-lo!

Se o Ghidra MCP economiza seu tempo, considere patrocinar o projeto. Tanto o suporte único quanto o recorrente ajudam a financiar atualizações de compatibilidade, robustez de produção, documentação e novas ferramentas.

Um servidor Model Context Protocol (MCP) pronto para produção que conecta as poderosas capacidades de engenharia reversa do Ghidra com ferramentas modernas de IA e frameworks de automação. 271 ferramentas MCP, fluxos de trabalho de IA testados em batalha e a integração Ghidra-MCP mais abrangente disponível — agora incluindo emulação P-code, integração com depurador ao vivo e análise de fluxo de dados via grafo PCode.

Por que Ghidra MCP?

A maioria das implementações Ghidra MCP oferece um punhado de ferramentas somente leitura e está tudo resolvido. Este projeto é diferente — foi construído por um engenheiro reverso que o usa diariamente em binários reais, não como uma demonstração.

• 271 ferramentas MCP — 3x mais que qualquer implementação concorrente. Não apenas operações de leitura — acesso total de escrita para renomeação, tipagem, comentários, criação de estruturas, execução de scripts, emulação P-code e depuração ao vivo.
• Fluxos de trabalho de IA testados em batalha — Fluxos de documentação comprovados (V5) refinados ao longo de centenas de funções. Inclui prompts passo a passo, referência de notação húngara, guias de processamento em lote e descoberta de código órfão.
• Confiabilidade de nível de produção — Transações atômicas, operações em lote (redução de 93% nas chamadas de API), timeouts configuráveis e tratamento gracioso de erros. Sem falhas silenciosas.
• Transferência de documentação entre binários — Correspondência de hash SHA-256 de funções propaga documentação entre versões de binários automaticamente. Documente uma vez, aplique em qualquer lugar.
• Integração completa com servidor Ghidra — Conecte-se a servidores Ghidra compartilhados, gerencie repositórios, controle de versão, fluxos de checkout/checkin e colaboração multiusuário.
• Modos headless e GUI — Execute com ou sem a interface gráfica do Ghidra. Pronto para Docker em pipelines CI/CD e análise automatizada em escala.
• Opinativo por design — A v5.0 move convenções de nomenclatura, segurança de tipos e padrões de documentação para a camada de ferramentas. Agentes de IA e engenheiros humanos produzem saída consistente sem guias de estilo em cada prompt.

Reforço de Convenções

Você já passou por isso: seis meses em um projeto você encontra ProcessItem, process_items, handleItem e ItemProc no mesmo código — quatro funções fazendo a mesma coisa, nomeadas por quatro sessões ou engenheiros diferentes sem um contrato compartilhado. Corrigir leva mais tempo do que deveria, e o problema vai acontecer de novo.

A v5.0 move as convenções de "coisas para lembrar" para a camada de ferramentas, onde elas podem realmente ser aplicadas.

Para agentes de IA, isso significa saída consistente em todas as sessões, todos os modelos, todas as execuções — sem colar um guia de estilo em cada prompt. A ferramenta conhece as regras; o modelo só precisa tomar a decisão.

Para equipes, elimina toda a classe de comentários de revisão que diz "essa não é nossa convenção de nomenclatura". A arbitragem de convenções fica na ferramenta, não na revisão de código.

Para trabalho solo em escala, analyze_function_completeness fornece uma pontuação de 0–100% que mede honestamente: deduções estruturais (artefatos de compilador não corrigíveis) são perdoadas em sua pontuação efetiva, a escala logarítmica impede que uma categoria ruim enterre todo o resto, e a qualidade comentada em níveis de placa significa que você sabe exatamente o que está faltando e por quê.

🌟 Recursos

Integração Principal MCP

• Compatibilidade Total com MCP — Implementação completa do Model Context Protocol
• 271 ferramentas MCP — Superfície de API abrangente cobrindo todos os aspectos da análise binária
• Confiabilidade de Nível de Produção — Transações atômicas, operações em lote, timeouts configuráveis
• Análise em Tempo Real — Integração ao vivo com o mecanismo de análise do Ghidra

Nota de compatibilidade: os nomes das ferramentas MCP são normalizados para o GitHub Copilot CLI e validação CAPI. Os nomes das ferramentas expostas usam apenas letras minúsculas, dígitos, underscores e hífens; caminhos HTTP aninhados como /debugger/status são anunciados como nomes como debugger_status_2 quando necessário para evitar colisões com ferramentas de ponte estáticas.

Capacidades de Análise Binária

• Análise de Funções — Decompilação, grafos de chamada, referências cruzadas, pontuação de completude
• Análise de Fluxo de Dados — Propagação de valor via grafo PCode (para frente/para trás) a partir de qualquer variável ou registrador
• Descoberta de Estruturas de Dados — Criação de struct/union/enum com análise de campos e sugestões de nomenclatura
• Extração de Strings — Busca por regex, filtragem de qualidade e descoberta de funções ancoradas em strings
• Análise de Import/Export — Tabelas de símbolos, localizações externas, resolução de imports por ordinal
• Inspeção de Memória e Dados — Leituras de memória bruta, busca de padrões de bytes, detecção de limites de arrays
• Documentação entre Binários — Correspondência de hash de funções e propagação de documentação entre versões

Análise Dinâmica (v5.4.0)

• Emulação P-code — Execute qualquer função isoladamente via EmulatorHelper do Ghidra; resolva hashes de API por força bruta em milissegundos
• Integração com Depurador ao Vivo — 17 endpoints Java + 22 ferramentas de ponte Python sobre o framework TraceRmi do Ghidra (dbgeng no Windows PE, gdb/lldb caso contrário): anexar, executar passo a passo, breakpoints, registradores, leituras de memória, rastreamento de funções sem interrupção, tradução de endereços estáticos↔dinâmicos com conhecimento de ASLR

Fluxos de Engenharia Reversa Potencializados por IA

• Fluxo de Documentação de Funções V5 — Processo de 7 etapas para documentação completa de funções com notação húngara, auditoria de tipos e pontuação de verificação automatizada
• Documentação em Lote — Despacho paralelo de subagentes para documentar múltiplas funções simultaneamente
• Descoberta de Código Órfão — Scanner automatizado encontra funções não descobertas em lacunas entre código conhecido
• Investigação de Tipos de Dados — Fluxos sistemáticos para descoberta de estruturas e análise de campos
• Correspondência entre Versões — Correspondência de funções baseada em hash entre diferentes versões de binários

Desenvolvimento e Automação

• Gerenciamento de Scripts do Ghidra — Crie, execute, atualize e exclua scripts do Ghidra inteiramente via MCP
• Suporte a Múltiplos Programas — Alterne e compare vários programas abertos
• Operações em Lote — Renomeação, comentários, tipagem e gerenciamento de rótulos em massa (93% menos chamadas de API)
• Servidor Headless — Análise completa sem interface gráfica do Ghidra — pronto para Docker e CI/CD
• Gerenciamento de Projetos e Controle de Versão — Crie projetos, gerencie arquivos, integração com servidor Ghidra
• Controle de Análise — Liste, configure e acione analisadores do Ghidra programaticamente

🚀 Início Rápido

Pré-requisitos

• Java 21 LTS (OpenJDK recomendado)
• Apache Maven 3.9+
• Ghidra 12.1.2 (ou versão compatível)
• Python 3.10+ com uv (recomendado) ou pip + venv

Usuários de servidor Ghidra compartilhado: clientes Ghidra 12.1.2 exigem um servidor Ghidra na versão 12.1, 12.0.5 ou uma versão compatível mais recente. Atualize o servidor antes de usar este plugin a partir de um cliente 12.1.

O Ghidra 12.1.2 inclui o Jython como uma extensão opcional. Scripts Java funcionam por padrão, mas scripts .py em ghidra_scripts/ exigem a instalação da extensão Jython em File > Install Extensions e reiniciar o Ghidra.

Instalação

Recomendado para todas as plataformas: use python -m tools.setup diretamente.

ensure-prereqs instala os requisitos de runtime Python e os JARs do Ghidra necessários no repositório Maven local. deploy copia a saída da build, instala a extensão do perfil de usuário e corrige a configuração do usuário do Ghidra.

1. Clone o repositório: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Recomendado: execute a verificação preliminar do ambiente primeiro: ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. Construir e implantar no Ghidra: ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy salva/fecha uma instância do Ghidra já em execução e correspondente quando necessário, instala a extensão, inicia o Ghidra, aguarda a saúde do MCP e executa verificações de fumaça no esquema.

4. Modo estrito/manual opcional (avançado): ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. Mostrar ajuda do comando: ```text python -m tools.setup --help
   root@kitploit:~

6. Modo opcional apenas de compilação (avançado/solução de problemas): ```text python -m tools.setup build
   root@kitploit:~

Caminho de build suportado: python -m tools.setup build usa Maven internamente e é o fluxo de trabalho canônico utilizado pelas tarefas e documentos do repositório. ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

INPUT:   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

Instalação (Linux — Ubuntu/Debian)

1. Clone o repositório: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Instalar pré-requisitos do sistema (se ainda não estiverem instalados): ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

Nota para Debian/Kali/Ubuntu 23.04+ (PEP 668): estas distribuições marcam o Python do sistema como gerenciado externamente, portanto um simples pip install falha com error: externally-managed-environment. Não contorne isso com --break-system-packages — isso pode corromper ferramentas gerenciadas pelo apt. Em vez disso, use uv (recomendado — ele cria e gerencia um .venv local ao projeto automaticamente, e é o que os comandos deste repositório usam):

root@kitploit:~

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # resolves deps into .venv and starts the bridge

ou um ambiente virtual clássico:

root@kitploit:~

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

3. Executar verificação prévia do ambiente: ```bash python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

4. Compilar e implantar no Ghidra (comando único): ```bash python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

Isto irá:

• Instalar dependências JAR do Ghidra no seu ~/.m2/repository local
• Construir GhidraMCP-<version>.zip com Maven
• Extrair a extensão para ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/
• Atualizar preferences com LastExtensionImportDirectory
• Instalar requisitos Python

5. Opcional: configurar apenas dependências Maven: ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. Mostrar ajuda do comando: ```bash python -m tools.setup --help
   root@kitploit:~

Caminhos no Linux: A extensão é instalada em $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/. Os arquivos de configuração do Ghidra estão em $HOME/.config/ghidra/ghidra_<version>_PUBLIC/.

Instalação (macOS — Homebrew)

1. Instalar pré-requisitos: ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. Clone o repositório: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. Instalar Ghidra JARs no Maven local: ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. Compilar e implantar: ```bash python -m tools.setup ensure-prereqs
   --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

A extensão é instalada em ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.

Nota: --ghidra-version é necessário ao usar o caminho do Homebrew porque o caminho não contém string de versão.

5. Inicie o Ghidra e ative o plugin: ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

Na janela principal do projeto: Tools > GhidraMCP > Start MCP Server

6. Configurar Cursor/Claude MCP (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

Instalação (Arch Linux — AUR)

@Pandoriaantje mantém pacotes comunitários do AUR:

• ghidra-mcp-git — segue o branch main
• ghidra-mcp — segue releases com tags

Instale com o seu helper AUR de preferência, ex.:```bash yay -S ghidra-mcp # or ghidra-mcp-git

### Uso Básico

#### Opção 1: Transporte Stdio (Recomendado para ferramentas de IA)```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

Para adicionar a bridge ao Autohand Code a partir de um checkout clonado:```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Adicione `--scope project` antes de `ghidra` para salvar o servidor na configuração `.autohand` do projeto atual em vez da sua configuração de usuário.

#### Opção 2: Transporte HTTP Streamable (Recomendado para clientes web/HTTP)```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

Configuração do cliente MCP para o transporte HTTP (adicione ao arquivo de configuração MCP do seu cliente):```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

Clientes baseados em navegador (ex.: [MCP Inspector](https://github.com/modelcontextprotocol/inspector))
funcionam imediatamente: os transportes HTTP respondem a requisições preflight CORS (`OPTIONS`) e expõem
os cabeçalhos `mcp-session-id` / `mcp-protocol-version` para scripts. Origens permitidas espelham a
política do cabeçalho Host — loopback em qualquer porta é sempre permitido, além do host de bind e quaisquer
hosts listados em `GHIDRA_MCP_ALLOWED_HOSTS`.

#### Opção 3: Transporte SSE (Obsoleto — use streamable-http em vez disso)```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

Bridge advanced flags

Roteamento estrito de programa (segurança multi-programa)

Defina GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 para fazer a ponte recusar qualquer chamada com escopo de programa que omita um seletor de programa, retornando um erro claro em vez de permitir que a chamada dependa do "programa atual" compartilhado do servidor (aquele que switch_program e a aba GUI ativa movem).```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

Sem isso, uma chamada que deixa `program=` de fora é executada contra o programa atual, o que é aceitável para um fluxo de trabalho com um único programa, mas perigoso quando vários programas estão abertos: a chamada pode ler ou editar o binário errado sem erro. O perigo é maior quando mais de um cliente compartilha um servidor, pois cada um move a variável global do programa atual sob os outros.

Com o modo estrito ativado, toda chamada com escopo de programa deve nomear seu alvo. Isso cobre todo seletor que escolhe um programa aberto: o simples `program=` e os `source_program`/`target_program` ou `program_a`/`program_b` das ferramentas entre programas (declarados obrigatórios, mas o servidor ainda recorre ao programa atual quando um chega vazio). Um seletor esquecido aparece como um erro alto na primeira chamada ruim, em vez de uma gravação silenciosa no binário errado. Ferramentas sem seletor de programa (`open_program` e `close_program` usam `path`/`name`) não são afetadas. Desativado por padrão: com a variável não definida, a ponte envia chamadas inalteradas.

#### Reduzindo a sobrecarga de contexto das ferramentas

A ponte expõe um grande catálogo. Para manter a superfície de ferramentas do modelo pequena, execute com `--lazy` (carrega apenas `listing,function,program` na conexão) e deixe o modelo **descobrir** o restante sob demanda, em vez de registrar tudo:

- `search_tools("rename function")` — pesquisa por palavra-chave no **catálogo inteiro**,
  incluindo ferramentas cujo grupo não está carregado. Cada resultado informa se a ferramenta está
  chamável agora e, se não, a chamada exata `load_tool_group(...)` para ativá-la.
- `list_tool_groups()` — lista todas as categorias e seu estado de carregamento.
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — carrega ou
  descarta uma categoria em tempo de execução.
- `check_tools("rename_or_label,batch_set_comments")` — confirma se ferramentas específicas
  estão chamáveis no momento.

`search_tools` funciona tanto no modo imediato quanto no `--lazy`, então agentes que honram `tools/list_changed` obtêm descoberta completa sem o custo de contexto adiantado.

#### Opcional: Iniciar o servidor de depuração independente```bash
uv sync --group debugger
uv run python -m debugger

O servidor debugger escuta em http://127.0.0.1:8099/ por omissão e é necessário para as ferramentas proxy debugger_* expostas pela ponte MCP.

Flags do servidor debugger:

Defina GHIDRA_DEBUGGER_URL no .env se alterar a porta ou o anfitrião padrão para que a ponte o consiga encontrar.

No Ghidra

1. Inicie o Ghidra e abra uma janela CodeBrowser
2. No CodeBrowser, ative o plugin através de File > Configure > Configure All Plugins > GhidraMCP
3. Opcional: configure a porta personalizada através de CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server
4. Inicie o servidor através de Tools > GhidraMCP > Start MCP Server
5. O servidor executa em http://127.0.0.1:8089/ por omissão

Verifique Que Está a Funcionar```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## Apoie Este Projeto

Se o Ghidra MCP economiza seu tempo de engenharia ou engenharia reversa, considere [patrocinar o projeto](https://github.com/sponsors/bethington).

- Patrocínio único ajuda a financiar correções, atualizações de compatibilidade e trabalho de lançamento.
- Patrocínio recorrente ajuda a manter a manutenção, documentação e hardening de produção em andamento.
- Suporte empresarial ajuda a priorizar a confiabilidade a longo prazo para a ponte, servidor headless, integração com depurador e ferramentas de fluxo de trabalho.

## 🔒 Segurança

O GhidraMCP é projetado para **desenvolvimento apenas em localhost**. A configuração padrão — servidor HTTP vinculado a `127.0.0.1`, sem autenticação — é segura em uma estação de trabalho confiável de usuário único e corresponde ao comportamento pré-v5.4.1.

**Se você expuser o servidor além do loopback, configure estas três variáveis de ambiente primeiro.** O servidor se recusa a iniciar em uma vinculação não-loopback sem um token.

| Variável de ambiente | Efeito |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | Quando definida, toda requisição HTTP deve conter `Authorization: Bearer <token>`. Comparação segura contra timing. `/mcp/health`, `/health`, `/check_connection` são isentos. |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | Defina como `1`, `true` ou `yes` para ativar `/run_script_inline` e `/run_ghidra_script`. **Desativado por padrão a partir da v5.4.1** — esses endpoints executam Java arbitrário contra o processo do Ghidra. No modo headless, isso também aciona a inicialização do `BundleHost` do OSGi na inicialização do servidor (framework Felix, ~centenas de ms); deixe desativado se você não precisar de execução de scripts. |
| `GHIDRA_MCP_FILE_ROOT` | Quando definida com um caminho de diretório, os endpoints de caminho de sistema de arquivos (`/load_program`, `/import_file`, `/open_project`, `/delete_file`, etc.) canonicalizam a entrada e exigem que ela esteja dentro desta raiz. Previne path-traversal. |

A aplicação da qualidade de nomes é separada da segurança. Por padrão, `rename_function_by_address` e endpoints de escrita global rejeitam nomes que falham nas verificações de qualidade internas, e escritas em campos de struct aplicam a convenção de prefixo de campo interna. Desative a camada de convenção interna com **Edit > Tool Options > GhidraMCP HTTP Server > Strict Naming Enforcement**. A mesma caixa de seleção em Tool Options cobre `rename_data`, `rename_global_variable`, `set_global`, o prefixo/guarda de tipo `apply_data_type`, e correções automáticas de prefixo húngaro em campos de struct em `create_struct`, `add_struct_field` e `modify_struct_field`. A configuração é lida quando o servidor MCP inicia ou reinicia. Avisos de convenção de função/global ainda são retornados quando a aplicação está desabilitada.

### Exemplo: expondo a uma LAN privada com autenticação```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

Autenticação do Servidor Ghidra

Quando se conecta a um Servidor Ghidra compartilhado, o GhidraMCP pode suprimir a caixa de diálogo de senha automaticamente. Ele resolve as credenciais nesta ordem (o primeiro valor não vazio vence):

Nota de compatibilidade: clientes Ghidra 12.1.2 exigem Servidor Ghidra 12.1.2, 12.0.5 ou um servidor compatível mais recente. Servidores compartilhados mais antigos não são alvos seguros para uma atualização do cliente 12.1.

1. Variável de ambiente GHIDRA_SERVER_PASSWORD (ou arquivo .env no diretório de instalação do Ghidra ou ~)
2. ~/.ghidra-cred — arquivo de senha de linha única no seu diretório home
3. <ghidra-install-dir>/.ghidra-cred

O nome de usuário é resolvido de forma similar: variável de ambiente GHIDRA_SERVER_USER → propriedade do sistema user.name.

Se nenhuma senha for encontrada, o Ghidra exibe seu prompt GUI normal. Defina essas opções em .env (veja .env.template para o bloco completo) para ativar a autenticação silenciosa.

Migração de v5.4.0 → v5.4.1

• Os endpoints de script agora estão desativados por padrão. Se você dependia de /run_script_inline ou /run_ghidra_script, exporte GHIDRA_MCP_ALLOW_SCRIPTS=1. Esta é uma mudança de quebra deliberada; o padrão anterior era inseguro.
• Implantações apenas em localhost não precisam de alterações. Autenticação, recusa de bind e verificações de path-root são todas opt-in.

❓ Solução de Problemas

Menu "GhidraMCP" não aparece em Ferramentas

Causa: Plugin não habilitado ou instalado incorretamente.

Solução:

1. Verifique se a extensão está instalada: File > Install Extensions — GhidraMCP deve estar listado
2. Habilite o plugin: File > Configure > Configure All Plugins > GhidraMCP (marque a caixa)
3. Reinicie o Ghidra após instalação/habilitação

Servidor não responde / Conexão recusada

Causa: Servidor não iniciado ou porta errada.

Solução:

1. Certifique-se de que iniciou o servidor: Tools > GhidraMCP > Start MCP Server
2. Verifique a porta configurada: Edit > Tool Options > GhidraMCP HTTP Server
3. Verifique se a porta está em uso: ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. Procure por erros no console do Ghidra: Window > Console

pip install falha com error: externally-managed-environment

Causa: PEP 668. Distribuições da família Debian (Debian 12+, Kali, Ubuntu 23.04+) marcam o Python do sistema como gerenciado externamente, então o pip install global é bloqueado para proteger pacotes gerenciados pelo apt.

Solução: Use um ambiente virtual — nunca --break-system-packages. O caminho recomendado é uv, que gerencia um .venv local ao projeto automaticamente:```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

Ou um venv clássico:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger falha com ModuleNotFoundError para pybag ou comtypes

Causa: O servidor de depuração autônomo usa dependências Python opcionais apenas para Windows que não são instaladas por padrão.

Solução:```text uv sync --group debugger uv run python -m debugger

Se você tiver tanto um Python global quanto um venv de projeto, certifique-se de instalar
e executar a partir do mesmo interpretador.

### 500 Erros Internos do Servidor

**Causa:** Exceção no servidor, geralmente devido à falta de dados do programa.

**Solução:**
1. Certifique-se de que um binário está carregado no CodeBrowser
2. Execute a análise automática primeiro: **Analysis > Auto Analyze**
3. Verifique o console do Ghidra (**Window > Console**) para exceções Java
4. Algumas operações exigem binários totalmente analisados

### 404 Erros Não Encontrados

**Causa:** O endpoint não existe ou URL incorreta.

**Solução:**
1. Verifique se o endpoint existe: `curl http://127.0.0.1:8089/get_version`
2. Verifique se há erros de digitação no nome do endpoint
3. Certifique-se de estar usando o método HTTP correto (GET vs POST)

### Scripts Python do Ghidra falham com "No script provider found"

**Causa:** No Ghidra 12.1.2, o suporte a Jython não está mais habilitado por padrão. Scripts `.py` precisam da extensão Jython empacotada; scripts Python 3 devem usar PyGhidra em vez do Gerenciador de Scripts do Ghidra.

**Solução:**
1. No Front End do Ghidra, vá em **File > Install Extensions**.
2. Marque **Jython**, reinicie o Ghidra e atualize o Gerenciador de Scripts.
3. Para novas automações, prefira scripts Java do Ghidra ou PyGhidra.

### Extensão não aparece em Instalar Extensões

**Causa:** O arquivo JAR está no local errado.

**Solução:**
1. Local de instalação manual: `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. Ou use: **File > Install Extensions > Add** e selecione o arquivo ZIP
3. Certifique-se de que o JAR/ZIP foi construído para sua versão do Ghidra

### Build falha com "Ghidra dependencies not found"

**Causa:** JARs do Ghidra não instalados no repositório Maven local.```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 Desempenho em Produção

• Ferramentas MCP: 271 ferramentas totalmente implementadas
• Velocidade: Resposta em menos de um segundo para a maioria das operações
• Eficiência: Redução de 93% nas chamadas de API via operações em lote
• Confiabilidade: Transações atômicas com semântica tudo-ou-nada
• Fluxos de Trabalho de IA: Prompts de documentação comprovados refinados em centenas de funções reais
• Implantação: Script de implantação automatizado ciente de versão

🛠️ Referência da API

271 ferramentas MCP suportadas por endpoints HTTP, agrupadas por categoria de catálogo. Gerado a partir de tests/endpoints.json por python -m tools.gen_readme_api_reference --write; o esquema ativo em /mcp/schema é autoritativo em tempo de execução. Padrões de uso: docs/prompts/TOOL_USAGE_GUIDE.md.

Gerenciamento de Programa e Sessão

• analysis_status - Obter status de análise automática para programas abertos
• close_program - Fechar um programa aberto pelo caminho do projeto ou nome
• create_property_map - Criar um mapa de propriedade do usuário para armazenar valores tipados chaveados por endereço
• delete_property_map - Excluir um mapa de propriedade do usuário e todos os valores que ele contém
• exit_ghidra - Salvar e sair do Ghidra
• get_address_spaces - Listar todos os espaços de endereço físicos e de sobreposição no programa (sobreposições incluem flag is_overlay e nome overlayed_space)
• get_current_program_info - Obter informações do programa atual
• get_language_metadata - Despejar a descrição da linguagem do programa: espaços de endereço, registradores, símbolos padrão, endianness, tamanho de ponteiro (issue #192)
• get_program_options - Ler todas as opções em um grupo de opções do programa com tipos, valores atuais, padrões e descrições
• get_property - Ler o valor armazenado em um endereço em um mapa de propriedade

Organização do Projeto

• create_folder - Criar uma pasta no projeto
• delete_file - Excluir um arquivo do projeto
• delete_project - Excluir um projeto Ghidra
• list_projects - Listar projetos Ghidra disponíveis
• move_file - Mover um arquivo para outra pasta do projeto
• move_folder - Mover uma pasta para outro local
• project_info - Obter informações detalhadas do projeto, incluindo ferramentas em execução e programas abertos

Ciclo de Vida de Projeto e Programa Headless

Disponível no servidor headless autônomo (GhidraMCPHeadlessServer).

• archive_project - Arquivar o projeto atualmente aberto em um arquivo .gar nativo do Ghidra
• checkin_program - Fazer check-in de um programa aberto de volta ao Servidor Ghidra compartilhado como uma nova versão
• close_project - Fechar o projeto atualmente aberto
• create_project - Criar um novo projeto Ghidra
• export_program - Exportar um programa aberto ou residente no projeto para um Arquivo Zip Ghidra (.gzf)
• get_project_info - Obter informações sobre o projeto atualmente aberto
• import_program - Importar um Arquivo Zip Ghidra (.gzf) para o projeto atualmente aberto como um novo DomainFile sob target_folder (padrão '/')
• load_program - Carregar um arquivo binário no servidor headless para análise
• load_program_from_project - Carregar programa a partir do projeto Ghidra (headless)
• open_project - Abrir um projeto Ghidra existente (arquivo .gpr ou diretório)
• restore_project - Restaurar um arquivo .gar do Ghidra em um novo projeto em disco em

Listagem e Enumeração

• list_bookmarks - Listar marcadores
• list_calling_conventions - Listar convenções de chamada disponíveis
• list_classes - Listar nomes de namespaces/classes
• list_data_items - Listar dados definidos
• list_data_items_by_xrefs - Listar dados ordenados por contagem de xrefs
• list_exports - Listar símbolos exportados
• list_external_locations - Listar locais externos
• list_functions - Listar funções com endereços
• list_functions_enhanced - Listar funções com metadados
• list_globals - Listar variáveis globais
• list_imports - Listar símbolos importados
• list_methods - Listar todos os nomes de funções com paginação

Contexto e Consultas

• get_current_address - Obter endereço do cursor (somente GUI)
• get_current_function - Obter função no cursor (somente GUI)
• get_current_selection - Obter intervalos de endereços destacados na listagem do CodeBrowser (somente GUI)
• get_entry_points - Obter pontos de entrada do programa
• get_enum_values - Obter valores de enumeração
• get_external_location - Obter detalhes do local externo
• get_full_call_graph - Obter grafo de chamadas completo
• get_function_by_address - Obter função no endereço
• get_function_call_graph - Obter grafo de chamadas
• get_function_callees - Obter funções chamadas
• get_function_callers - Obter funções que chamam
• get_function_count - Retornar o número de funções no programa carregado

Pesquisa

• find_similar_functions - Encontrar funções semelhantes
• search_byte_patterns - Pesquisar padrões de bytes
• search_data_types - Pesquisar tipos de dados
• search_functions - Pesquisar funções por nome
• search_functions_enhanced - Pesquisa avançada de funções
• search_strings - Pesquisar strings definidas por um padrão de regex/substring

Descompilação e Desmontagem

• decompile_function - Descompilar função
• disassemble_bytes - Desmontar intervalo de bytes
• disassemble_function - Desmontar função
• force_decompile - Forçar descompilação nova

Tags de Função, Variáveis e Atributos

• add_function_tag - Anexar uma ou mais tags a uma função
• batch_add_function_tags - Anexar tags a várias funções em uma transação
• batch_remove_function_tags - Desanexar tags de várias funções em uma transação
• clear_flow_and_repair - Executar a ação 'Clear Flow and Repair' da GUI do Ghidra em um intervalo de semente: limpa o fluxo de instruções alcançável a partir da semente, então repara corpos de função e remonta o fluxo retido (ClearFlowAndRepairCmd com clear_data=false, clear_labels=false, repair=true)
• create_function_tag - Criar uma definição de tag de função em todo o programa com um comentário opcional
• delete_function_tag - Excluir uma definição de tag de função em todo o programa
• get_function_tags - Listar todas as tags atribuídas a uma função específica
• list_class_members - Listar as funções membro de uma classe C++
• list_function_tags - Listar todas as definições de tag de função em todo o programa com suas contagens de uso
• remove_function_tag - Desanexar uma ou mais tags de uma função

Referências Cruzadas

• add_memory_reference - Criar uma referência cruzada definida pelo usuário entre dois endereços de memória que o analisador automático não pode inferir (tabelas de ponteiros preenchidas em tempo de execução, vtables, ponteiros de função vinculados tardiamente, tabelas de salto/switch perdidas)
• get_bulk_xrefs - Obter xrefs para múltiplos endereços
• get_function_xrefs - Obter referências cruzadas de função
• get_xrefs_from - Obter referências a partir do endereço
• get_xrefs_to - Obter referências para o endereço
• remove_reference - Remover referência(s) cruzada(s) de memória de um endereço para outro — o inverso de add_memory_reference

Tipos de Dados e Estruturas

• add_struct_field - Adicionar campo de estrutura
• analyze_global_completeness - Pontuar a completude da documentação de uma variável global em uma escala orçada de 0 a 100 — o análogo de endereço de dados de analyze_function_completeness
• apply_data_type - Aplicar tipo de dados
• audit_global - Auditar o estado da documentação de uma variável global
• audit_globals_in_function - Auditar todas as variáveis globais referenciadas dentro de uma função em uma chamada
• batch_set_variable_types - Definir múltiplos tipos de variáveis
• clone_data_type - Clonar tipo de dados
• create_array_type - Criar tipo array
• create_data_type_category - Criar categoria de tipo de dados
• create_enum - Criar enumeração
• create_function_signature - Criar tipo de assinatura de função

Renomeação e Rótulos

• batch_create_labels - Criar múltiplos rótulos
• batch_delete_labels - Excluir múltiplos rótulos
• batch_rename_function_components - Renomear componentes de função em lote
• create_label - Criar rótulo
• delete_label - Excluir rótulo no endereço
• rename_data - Renomear símbolo de dados
• rename_external_location - Renomear local externo
• rename_function - Renomear função por nome
• rename_function_by_address - Renomear função por endereço
• rename_global_variable - Renomear variável global
• rename_label - Renomear rótulo
• rename_or_label - Renomear ou criar rótulo

Comentários e Marcadores

• batch_set_comments - Definir múltiplos comentários
• clear_function_comments - Limpar todos os comentários de uma função
• delete_bookmark - Excluir marcador
• get_comment - Obter comentários de listagem (placa/pré/eol/pós/repetível) em QUALQUER endereço, incluindo endereços de dados (diferente de get_plate_comment que requer uma função)
• get_plate_comment - Obter comentário de placa
• set_bookmark - Definir marcador
• set_comment - Definir um comentário de listagem de um tipo específico (placa/pré/eol/pós/repetível) em QUALQUER endereço, incluindo endereços de dados
• set_decompiler_comment - Definir PRE_COMMENT
• set_disassembly_comment - Definir EOL_COMMENT
• set_plate_comment - Definir comentário de placa

Análise

• analyze_api_call_chains - Analisar cadeias de chamadas de API
• analyze_call_graph - Analisar padrões de grafo de chamadas de função
• analyze_control_flow - Analisar fluxo de controle
• analyze_data_region - Analisar região de dados
• analyze_dataflow - Rastrear propagação de valor através de uma função (grafo PCode, para frente/para trás)
• analyze_for_documentation - Análise de documentação RE composta (descompilar + classificar + variáveis + completude)
• analyze_function_complete - Análise abrangente de função com uma única chamada
• analyze_function_completeness - Analisar completude da documentação
• analyze_struct_field_usage - Analisar uso de campo de estrutura
• apply_data_classification - Aplicar classificação de dados
• batch_analyze_completeness - Analisar completude em lote para múltiplas funções

Documentação e Arquivo Cruzado entre Binários

• archive_ingest_function - Ingerir a documentação de uma única função no arquivo entre versões (re_kb.functions no bsim Postgres)
• archive_ingest_program - Ingerir em massa todas as funções em um programa no arquivo de documentação entre versões
• batch_string_anchor_report - Relatório de strings de arquivo fonte e suas funções FUN_*
• bulk_fuzzy_match - Correspondência de função entre binários em massa
• find_similar_functions_fuzzy - Correspondência de função difusa entre binários
• merge_program_documentation - Mesclagem em massa: copiar toda a documentação RE (nomes de função, assinaturas, comentários de placa, comentários de instrução em EOL/PRE/POST, rótulos não padrão e símbolos globais) de um programa para outro em endereços correspondentes

Utilitário e Transferência de Documentação

• apply_function_documentation - Aplicar documentação de função
• check_connection - Endpoint de verificação de saúde
• compare_programs_documentation - Comparar documentação entre programas
• convert_number - Converter número entre bases
• diff_functions - Diferenciar duas funções
• find_undocumented_by_string - Encontrar funções não documentadas que referenciam string
• get_bulk_function_hashes - Obter hashes de função em massa
• get_function_documentation - Exportar documentação de função
• get_function_hash - Obter hash de função
• get_function_signature - Obter assinatura de recurso da função
• get_metadata - Obter metadados do programa
• get_version - Obter versão do plugin

Emulação

• emulate_function - Emular uma única função com entradas de registrador/memória controladas
• emulate_hash_batch - Resolução de hash de API por força bruta

Scripts

• run_ghidra_script - Executar script com captura de saída
• run_script_inline - Executar código de script inline

Servidor Ghidra e Controle de Versão

• server_admin_set_permissions - Definir permissões de usuário em um repositório
• server_admin_terminate_all_checkouts - Encerrar todos os checkouts em uma pasta recursivamente
• server_admin_terminate_checkout - Encerrar todos os checkouts em um único arquivo
• server_admin_users - Listar todos os usuários no servidor
• server_authenticate - Registrar credenciais do servidor para autenticação programática
• server_checkouts - Listar todos os arquivos com checkout em uma pasta, incluindo checkouts do lado do servidor
• server_connect - Conectar a um servidor Ghidra
• server_disconnect - Desconectar do servidor Ghidra
• server_repositories - Listar repositórios no servidor conectado
• server_repository_create - Criar um novo repositório no servidor
• server_repository_file - Obter informações do arquivo de um repositório do servidor

Depurador (Ghidra TraceRmi — somente GUI)

Em hosts Windows onde o proxy do depurador WinDbg da ponte está ativo (GHIDRA_DEBUGGER_URL), nomes conflitantes recebem um sufixo _2 (ex. debugger_status_2).

• debugger_dynamic_to_static - Traduzir um endereço dinâmico de tempo de execução do trace atual de volta para um endereço de programa Ghidra estático
• debugger_interrupt - Interromper (invadir) o alvo em execução
• debugger_launch - Lançar um executável através do lançador do depurador Trace RMI do Ghidra
• debugger_launch_offers - Listar opções disponíveis de lançamento/anexação do depurador para o programa atual
• debugger_list_breakpoints - Listar todos os pontos de interrupção no trace atual
• debugger_modules - Listar módulos (DLLs/EXEs) carregados no processo depurado
• debugger_read_memory - Ler memória do processo depurado
• debugger_registers - Ler registradores da CPU do snapshot de trace de depuração atual
• debugger_remove_breakpoint - Remover um ponto de interrupção em um endereço
• debugger_resume - Retomar a execução do processo depurado
• debugger_set_breakpoint - Definir um ponto de interrupção de execução de software em um endereço no trace

Sistema

• prompt_policy - Ativar, desativar ou consultar temporariamente o tratamento de prompts de automação com escopo

Ferramentas Estáticas da PonteDefinido na própria ponte Python (descoberta de instância, gerenciamento de grupos de ferramentas); sempre disponível mesmo antes de uma conexão com o Ghidra. A ponte também faz proxy de 22 ferramentas WinDbg debugger_* quando GHIDRA_DEBUGGER_URL aponta para o servidor de depuração independente.

• check_tools - Relatar quais ferramentas estão atualmente registradas e podem ser chamadas
• connect_instance - Conectar a ponte a uma instância específica do Ghidra
• import_file - Importar um binário do disco para o projeto atual e abri-lo
• list_instances - Descobrir instâncias Ghidra MCP em execução (UDS + varredura de porta TCP)
• list_tool_groups - Listar grupos de ferramentas e seu estado de carregamento
• load_tool_group - Registrar as ferramentas dinâmicas de um grupo de ferramentas no cliente MCP
• search_tools - Pesquisar todo o catálogo de ferramentas por palavra-chave
• unload_tool_group - Cancelar o registro das ferramentas dinâmicas de um grupo de ferramentas

Veja CHANGELOG.md para o histórico de versões.

🏗️ Arquitetura```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### Componentes

- **python/bridge_mcp_ghidra/** — Pacote servidor MCP em Python (distribuído como a wheel `ghidra-mcp-bridge`; script de console `bridge-mcp-ghidra`) que traduz o protocolo MCP para chamadas HTTP (225 entradas de catálogo)
- **GhidraMCP.jar** — Plugin do Ghidra que expõe capacidades de análise via HTTP (175 endpoints de GUI)
- **GhidraMCPHeadlessServer** — Servidor headless autônomo — 183 endpoints, sem necessidade de GUI
- **ghidra_scripts/** — Coleção de scripts de automação para tarefas comuns

## 🔧 Desenvolvimento

### Compilando a partir do Código Fonte```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

O sistema de build autoritativo hoje é o Maven. tools.setup, as tarefas do VS Code e o fluxo de deploy documentado constroem todos através do pom.xml e escrevem artefatos em target/. O build.gradle permanece no repositório como um fallback manual para usuários diretos do Ghidra/Gradle, mas não é o caminho principal.

Referência de Comandos

Flags comuns aceitas pela maioria dos comandos:

Os tiers de teste de deploy são opt-in porque os tiers de benchmark podem importar/redefinir Benchmark.dll e BenchmarkDebug.exe no projeto Ghidra ativo. Use --test release antes de lançar versões, ou defina GHIDRA_MCP_DEPLOY_TESTS=release em um .env local quando quiser que cada deploy na sua máquina execute a regressão de benchmark ao vivo. Veja Testes e Regressão de Lançamento.```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### Estrutura do Projeto```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

Dependências de Biblioteca

Os JARs do Ghidra devem ser instalados no repositório Maven local (~/.m2/repository) antes da compilação. Esta é uma configuração única por máquina, e novamente quando sua versão do Ghidra for alterada. -Deploy agora instala estes automaticamente por padrão.

A ferramenta impõe consistência de versão entre:

• pom.xml (ghidra.version)
• segmento de versão de --ghidra-path (ex.: ghidra_12.1.2_PUBLIC)

Se estes não coincidirem, a implantação falha rapidamente com um erro claro.

Solução de Problemas: Incompatibilidade de Versão

Se você vir um erro de incompatibilidade de versão, alinhe ambos os valores:

1. pom.xml → ghidra.version
2. segmento de versão de --ghidra-path (ghidra_X.Y.Z_PUBLIC)

Em seguida, execute novamente:```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

[No input content provided. Please paste the Markdown text you wish to have translated.]```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

Bibliotecas Necessárias (14 JARs, ~37MB):

Nota: As bibliotecas NÃO estão incluídas no repositório (veja .gitignore). Você deve instalá-las a partir da sua instalação do Ghidra antes de compilar.

Ponto de entrada de automação:

• python -m tools.setup é a interface suportada para configuração/compilação/implantação/versionamento
• use ensure-prereqs, build, deploy, preflight, clean-all e bump-version diretamente
• esses comandos atualmente usam Maven como backend de compilação Java canônico

Funcionalidades de Desenvolvimento

• Implantação Automatizada: Script de implantação ciente de versão
• Operações em Lote: Reduz chamadas de API em 93%
• Transações Atômicas: Semântica tudo-ou-nada
• Registro Abrangente: Capacidades de depuração e rastreamento

📚 Documentação

Documentação Principal

• Índice de Documentação - Navegação completa da documentação
• Estrutura do Projeto - Guia de organização do projeto
• Testes e Regressão de Lançamento - Testes locais, CI, regressão ao vivo do Ghidra e portões de lançamento
• Convenções de Nomenclatura - Padrões de nomenclatura de código
• Notação Húngara - Guia de nomenclatura de variáveis

Prompts de Fluxo de Trabalho de IA

• Documentação de Funções V5 — Fluxo principal: processo de 7 etapas com notação húngara, auditoria de tipos e pontuação de verificação
• Documentação em Lote V5 — Despacho paralelo de subagentes para processamento de múltiplas funções
• Descoberta de Código Órfão — Scanner automatizado para funções não descobertas
• Investigação de Tipos de Dados — Descoberta sistemática de estruturas
• Correspondência Entre Versões — Correspondência de funções baseada em hash
• Prompt de Início Rápido — Fluxo de trabalho simplificado para iniciantes
• Todos os Prompts — Índice completo de prompts

Histórico de Lançamentos

• Changelog Completo - Notas de lançamento de todas as versões
• Notas de Lançamento - Documentação detalhada de lançamentos

🐳 Servidor Headless (Docker)

GhidraMCP inclui um modo de servidor headless para análise automatizada sem a GUI do Ghidra.

Início Rápido com Docker```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### Fluxo de Trabalho da API Headless```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

Principais Endpoints Headless

Configuração

Variáveis de ambiente para Docker:

• GHIDRA_MCP_PORT - Porta do servidor (padrão: 8089)
• GHIDRA_MCP_BIND_ADDRESS - Endereço de vinculação (padrão: 0.0.0.0 no Docker)
• JAVA_OPTS - Opções JVM (padrão: -Xmx4g -XX:+UseG1GC)

🤝 Contribuindo

Consulte CONTRIBUTING.md para diretrizes detalhadas de contribuição.

Início Rápido

1. Fork o repositório
2. Crie uma branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Compile e teste suas alterações (mvn clean package assembly:single -DskipTests ou GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. Atualize a documentação conforme necessário
5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
6. Envie para a branch (git push origin feature/amazing-feature)
7. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença Apache 2.0 - consulte o arquivo LICENSE para obter detalhes.

🏆 Status de Produção

Consulte CHANGELOG.md para histórico de versões e notas de lançamento.

🙏 Agradecimentos

Este projeto foi originalmente derivado de LaurieWired/GhidraMCP em agosto de 2025 e desde então foi substancialmente reescrito e estendido. Reconhecemos o trabalho original de LaurieWired como ponto de partida. Consulte NOTICE para atribuição de licença.

👥 Contribuidores

Este projeto se beneficiou do trabalho de contribuidores dedicados:

Contribuidores Principais

@heeen — Contribuições significativas incluindo:

• Correspondência difusa de funções e diff estruturado para comparação entre binários (#13)
• Melhorias na execução de scripts e correções de bugs (#12)
• Novos endpoints de API: save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• Visão arquitetural: design orientado a anotações, transporte UDS, propostas de otimização da ponte Python

@huehuehuehueing — Contribuições significativas incluindo:

• Suporte a prefixo de espaço de endereço — adicionou a sintaxe <space>:<hex> (ex.: mem:1000, code:ff00) à análise de endereços em toda a superfície de endpoints, desbloqueando alvos multi-espaço como firmware embarcado (#84, closes #65)

• Parâmetro program opcional + correções de esquema de parâmetros obrigatórios — tornou program opcional em todos os endpoints com um fallback sensato de currentProgram, e corrigiu vários bugs de esquema obrigatório-vs-opcional que o catálogo havia herdado (#92)

• Originou #44 (ferramentas de tipo de dado / enum) — a questão que motivou a camada de aplicação de enum + struct da v5.0

• Equipe Ghidra - Pela incrível plataforma de engenharia reversa

• Model Context Protocol - Pelo framework padronizado de integração com IA

• Contribuidores - Pelos testes, feedback e melhorias

🔗 Projetos Relacionados

• re-universe — Plataforma Ghidra BSim PostgreSQL para análise de similaridade binária em larga escala. Combina perfeitamente com GhidraMCP para fluxos de trabalho de engenharia reversa orientados por IA.
• cheat-engine-server-python — Servidor MCP para análise dinâmica de memória e depuração.

Pronto para implantação em produção com confiabilidade de nível empresarial e capacidades abrangentes de análise binária.