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, 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 e a FlatProgramAPI 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 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

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

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.

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

Conteúdo