Python Command-Line Ghidra MCP

Para iniciar e controlar uma GUI do Ghidra ao vivo 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

Otimizado para Agentes

pyghidra-mcp mantém a superfície MCP intencionalmente estreita para que clientes agentes gastem menos tokens na descoberta de ferramentas e seleção de argumentos.

• Descrições curtas de ferramentas: As docstrings das ferramentas MCP são mantidas compactas para que os esquemas de ferramentas FastMCP permaneçam pequenos e baratos de enviar para os modelos.
• Disciplina de contexto: as ferramentas retornam dados estruturados focados em vez de despejar o contexto completo do programa por padrão. Os resultados de descompilação, busca de símbolos e referências cruzadas são moldados para suportar análise iterativa em vez de uma única resposta grande.
• Ferramentas GUI apenas quando relevantes: controles exclusivos da GUI, como open_program_in_gui, list_open_programs, set_current_program e goto, são expostos apenas quando o servidor é iniciado com --gui.
• CLI é opcional: se o MCP não for 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 ferramenta desnecessária ou controles exclusivos da 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 (recomendado):```bash uvx pyghidra-mcp-cli

Início Rápido com CLI

1. Inicie o servidor (em um terminal):```bash pyghidra-mcp --transport streamable-http /bin/ls

[!NOTE] A CLI se conecta ao pyghidra-mcp via HTTP para evitar a sobrecarga de inicialização de 10 a 60 segundos ao gerar um novo processo Ghidra para cada comando. Consulte o CLI README para obter a 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 possui seu próprio projeto Ghidra e artefatos pyghidra-mcp. Isso garante isolamento completo e fácil gerenciamento 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

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

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 um 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
• As ferramentas exclusivas da GUI são expostas apenas quando executadas com --gui

Exemplo:

O modo GUI é a escolha certa quando você quer:

• abrir ou alternar programas no CodeBrowser
• navegar na listagem para uma função ou endereço
• renomear funções ou adicionar comentários e ver imediatamente essas alterações no Ghidra

Padrões de Inicialização e Projetos Grandes

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

• a descompilação, navegação, renomeação e comentários ainda podem funcionar para um binário enquanto os recursos de busca intensiva em indexação estão alcançando
• se a latência de inicialização é mais importante do que a prontidão imediata da busca, mantenha o padrão --no-wait-for-analysis
• se a prontidão imediata é mais importante do que o tempo de inicialização, use --wait-for-analysis

Desenvolvimento

Este projeto usa um Makefile para otimizar o desenvolvimento e teste. ruff é usado para linting e formatação, e hooks 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 o pip:

   root@kitploit:~

   pip install uv
   

   Ou siga o guia oficial de instalação do uv: https://docs.astral.sh/uv/install/

2. Crie um ambiente virtual e instale as dependências:

   root@kitploit:~

   make dev-setup
   source ./.venv/bin/activate
   

3. Defina a Variável de Ambiente do Ghidra: Baixe e instale o Ghidra, então defina a variável de ambiente GHIDRA_INSTALL_DIR para o diretório de instalação do seu Ghidra.

   root@kitploit:~

   # For Linux / Mac
   export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
   
   # For Windows PowerShell
   [System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
   

Testes e Qualidade

O Makefile fornece vários alvos para teste e qualidade do código:

• make run: Execute o servidor MCP.
• make test: Execute a suíte de testes completa (unitários e de integração).
• make test-unit: Execute testes unitários.
• make test-integration: Execute testes de integração.
• make test-integration-fast: Execute o teste de fumaça de integração leve usado pelo pre-commit.
• make test-integration-gui: Execute testes de integração GUI. Requer uma instalação funcional do Ghidra e suporte GUI.
• make lint: Verifique o estilo do código com ruff.
• make format: Formate o código com ruff.
• make typecheck: Execute verificações estáticas leves com ruff.
• make check: Execute todas as verificações de qualidade.
• make dev: Execute o fluxo de trabalho de desenvolvimento (formatar e verificar).
• make build: Construa pacotes de distribuição.
• make clean: Limpe artefatos de construção e cache.

Divisão recomendada:

• pre-commit: ruff, pyright, testes unitários e um teste de fumaça de integração leve
• GitHub Actions: cobertura total de integração headless no Linux, GUI Linux sob Xvfb, cobertura CLI e testes de fumaça atuais no macOS
• CI agendado: cobertura de compatibilidade com macOS / Ghidra antigos
• local/manual: depuração GUI mais pesada específica do ambiente e verificações de sanidade de lançamento

API

Ferramentas

Permite que LLMs realizem 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 viagens de ida e volta 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"] }

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 destino 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 destino) e 'called' (funções que chamam o destino) 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 destino ou uma lista para descompilação em lote. Flags de resposta ricas anexam callees, strings e/ou xrefs a cada resultado. timeout_sec é aplicado por destino 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 consulta).

• 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 consulta).

• 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 insensível a maiúsculas/minúsculas, ou consultas de substring simples. Defina functions_only=True para excluir rótulos, variáveis e outros símbolos que não sejam 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 irá escanear e importar recursivamente 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 em disco mesmo se não estiverem 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 ao vivo do Ghidra 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 pelo 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 ao vivo do Ghidra 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 pelo 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 analisador de tipo de dado do Ghidra contra o gerenciador de tipo de dado 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 passa o protótipo pelo analisador de assinatura nativo do Ghidra e retorna o analisador subjacente ou erro 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. Os alvos do 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 (somente --gui)

Essas ferramentas estão disponíveis apenas quando pyghidra-mcp é iniciado com --gui e controlam o que a GUI está exibindo, em vez de alterar dados do projeto diretamente:

• 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, 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 e pode ser instalado e executado com pip, pipx, uv, poetry 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.

Usando com OpenWeb-UI e MCPO

Você pode integrar o pyghidra-mcp com o OpenWeb-UI usando o MCPO, um proxy MCP-to-OpenAPI. Isso permite expor as ferramentas do pyghidra-mcp através de uma API RESTful padrão, tornando-as acessíveis a interfaces web e outras ferramentas.

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

Com uvx

Você pode executar pyghidra-mcp e mcpo juntos usando uvx:```bash uvx mcpo --
pyghidra-mcp /bin/ls

Entrada/Saída Padrão (stdio)

O transporte stdio permite comunicação através de fluxos de entrada e saída padrão. Isso é particularmente útil para integrações locais e ferramentas de linha de comando. Consulte a especificação para mais detalhes.

Python```bash

pyghidra-mcp

Por padrão, o contêiner Docker inicia o servidor streamable-http, portanto inclua -t stdio após o nome da imagem e execute com -i para o modo stdio interativo.

Streamable HTTP

O Streamable HTTP permite respostas em streaming sobre JSON RPC via requisições HTTP POST. Consulte a especificação para mais detalhes.

Por padrão, o servidor escuta em 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

Docker```

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

Por padrão, o pacote Python será executado no modo stdio, então você terá que incluir -t sse.

Docker```

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

Inspiração

Este projeto foi inspirado por estes projetos incríveis:

• GhidraMCP
• semgrep-mcp
• ghidrecomp
• BinAssistMCP

Contribuição, comunidade e execução a partir do código-fonte

Acreditamos que o futuro da engenharia reversa é agentivo, contextual e escalável.
pyghidra-mcp é um passo em direção a esse futuro—tornando projetos completos do Ghidra acessíveis a agentes de IA e pipelines de automação.

Estamos desenvolvendo ativamente o projeto e recebemos feedback, issues e contribuições.

[!NOTE] Adoramos seu feedback, relatórios de bugs, solicitações de recursos e código.

Fluxo de trabalho do colaborador

Se você está adicionando uma nova ferramenta ou integração, aqui está o fluxo de trabalho recomendado:

• Rotule seu branch com o prefixo feature/ para indicar uma nova funcionalidade.
• Adicione sua ferramenta usando o mesmo estilo e estrutura das ferramentas existentes em pyghidra/tools/.
• Escreva um teste de integração que exercite sua ferramenta usando uma instância de StdioClient. Coloque-o em tests/integration/.
• Estenda os testes concorrentes adicionando uma chamada para sua ferramenta em tests/integration/test_concurrent_streamable_client.py.
• Execute make test e make format para garantir que suas alterações passem em todos os testes e estejam em conformidade com as regras de linting.

Isso garante consistência em toda a base de código e nos ajuda a manter ferramentas robustas e escaláveis para fluxos de trabalho de engenharia reversa.

Feito com ❤️ pela Equipe PyGhidra-MCP