DOCSEARCHbyAlgolia
Submit Docs

Ghidra MCP Server

repository·main·Indexed 25 days ago

https://github.com/bethington/ghidra-mcp

A Model Context Protocol (MCP) implementation and HTTP multiplexer (ghidra-mcp-bridge) that provides AI agents with bidirectional access to Ghidra's reverse engineering engine. It features a headless REST API for binary analysis, program management, and decompilation, along with specialized AI workflows for function documentation, data type investigation, and cross-binary matching.

Tokens
79.4K
Snippets
130
Records
376
Agent score
85%

What's inside ghidra-mcp

  1. Overview of Ghidra MCP Server

    main

    Ghidra MCP Server is a production-ready Model Context Protocol (MCP) server that bridges Ghidra's reverse engineering capabilities with AI tools and automation frameworks. It provides 272 MCP tools for binary analysis, including full write access for renaming, typing, commenting, and script execution.

    Key capabilities include:

    • Binary Analysis: Decompilation, call graphs, cross-references, and PCode-graph data flow analysis.
    • Dynamic Analysis (v5.4.0+): P-code emulation and live debugger integration (via Ghidra's TraceRmi framework).
    • AI Workflows: Automated function documentation (V5), batch processing, and orphaned code discovery.
    • Convention Enforcement: Automated enforcement of naming conventions and type safety through Auto-fix, Warn, and Reject tiers.

  2. Understand the Ghidra MCP Architecture

    main

    The Ghidra MCP system consists of three primary layers that enable AI and automation tools to interact with Ghidra:

    1. AI/Automation Tools: Clients (like Claude) that communicate via the MCP Protocol (stdio or streamable-http).
    2. MCP Bridge (python/bridge_mcp_ghidra/): A Python package that translates MCP protocol requests into HTTP REST calls. It provides 225 catalog entries.
    3. Ghidra Plugin (GhidraMCP.jar): A Java plugin that exposes Ghidra's internal APIs (Program, Listing) via HTTP REST. It provides 175 GUI endpoints.

    Additionally, a GhidraMCPHeadlessServer is available for standalone headless operation (183 endpoints), and a collection of automation scripts is located in ghidra_scripts/ for common tasks.

  3. Understand Headless vs GUI Parity in Ghidra MCP

    main

    Ghidra MCP operates in two modes: GUI and headless. While GUI mode is interactive, headless mode is designed for long-running automation, CI, batch documentation, and server-side reverse-engineering.

    Users should be aware that not all endpoints are available in headless mode. When an endpoint is unsupported in the current runtime, the server returns a structured error rather than hiding the endpoint from the schema. This allows AI agents and users to understand that the capability exists but is unavailable in the current mode.

  4. Understand Dynamic Knowledge Validation

    main

    Dynamic Knowledge Validation is a proposed workflow in Ghidra MCP that uses live debugger evidence to verify, correct, and expand the static Ghidra knowledge corpus. Instead of relying solely on static analysis, this feature uses runtime captures (registers, stack, return values, etc.) to validate function prototypes, calling conventions, and data structures.

    Key capabilities include:

    • Runtime Prototype Validation: Verifying argument counts, types, calling conventions, and return values.
    • Runtime Data Structure Discovery: Observing pointer fields, allocation patterns, and object lifetimes.
    • Runtime Call Graph and Behavior Tracing: Capturing real caller/callee paths and execution flows.

  5. Understand the Gradle and Python ownership model

    main

    After the migration, the project follows a split ownership model between Gradle and Python. Developers should follow these boundaries:

    Gradle Ownership

    • Java/plugin compilation, testing, and packaging.
    • Validation (version and preflight checks).
    • Deployment (copying archives, patching Ghidra configs).
    • Launching Ghidra.

    Python Ownership

    • Runtime systems (e.g., bridge_mcp_ghidra.py, debugger/, fun-doc/).
    • Python dependency management (pip/environment).
    • Repository/Release tooling (e.g., tools.setup bump-version).
    • The tools.setup CLI facade.

  6. Understand the Native MCP Runtime Architecture

    main

    The Ghidra MCP project is migrating from a Python-based bridge architecture to a Native MCP Runtime implemented directly in Java using the official Java MCP SDK.

    Current Architecture (Legacy)

    AI Tool -> MCP -> bridge_mcp_ghidra.py -> HTTP/UDS/TCP -> Ghidra Java server

    Target Architecture (Native)

    • Headless Mode: AI Tool -> MCP stdio/streamable HTTP -> Ghidra Java headless server
    • GUI Mode: AI Tool -> MCP streamable HTTP -> Ghidra GUI plugin

    The Python bridge (bridge_mcp_ghidra.py) and legacy HTTP endpoints will remain supported as fallbacks during the migration period.

  7. Understand the Diablo II Version Landscape and Clusters

    main

    Versions of Diablo II are grouped into clusters based on code similarity. Use these clusters to determine your matching strategy:

    • Classic (1.00-1.06b): Pre-LoD. Use hash matching within the cluster; use strings or callgraphs to bridge to LoD.
    • Early LoD (1.07-1.10): "Stable LoD". High hash match rate (~40-60%) within the cluster.
    • Refactor (1.10→1.11): "The Great Refactor". Requires complex matching using strings, callgraphs, and structure due to major DLL reorganization and calling convention changes.
    • Modern LoD (1.11-1.14d): "Post-Refactor". High hash match rate (~50-70%) within the cluster.
    • PD2/Mods: Based on 1.13c/1.14d; high match to Modern LoD.

  8. Understand the Documentation Propagation logic

    main

    The system uses two primary methods to ensure documentation remains accurate even when binary addresses change between versions:

    Hash-Based Function Matching

    Instead of using absolute addresses, the system uses a normalized opcode hash (SHA-256). This allows the system to identify identical logic at different memory addresses. External calls and data references are abstracted as placeholders to maintain stability.

    Offset-Based Global Matching

    To solve the issue of global variables not propagating when function addresses change, the system uses an offset-based approach:

    • Storage: It stores the instruction_offset + operand_index + extracted_address relative to the function entry point.
    • Retrieval: At runtime, it navigates to function_entry + offset to dynamically locate and rename globals.

  9. Navigate the Ghidra MCP project structure

    main

    The repository is organized into several key functional areas:

    • python/bridge_mcp_ghidra/: The Python MCP bridge package (distributed as the ghidra-mcp-bridge wheel).
    • src/: Contains Java source code for the GUI plugin and headless server. MCP endpoints are located under src/main/java/com/xebyte/.
    • debugger/: A standalone Python debugger server used by the bridge when debugger support is enabled.
    • ghidra_scripts/: Scripts designed to be executed within Ghidra's internal Script Manager.
    • tests/: Python unit, integration, and performance tests. The file tests/endpoints.json serves as the maintained endpoint catalog snapshot.
    • docs/: Maintained documentation. Use docs/README.md as the primary entry point. Prompt documentation is located in docs/prompts/ and release notes in docs/releases/.

  10. Understand the two Ghidra variable systems

    main

    Ghidra uses two distinct variable naming systems. To implement variable renaming correctly, you must distinguish between Storage-Based Variables and Decompiler SSA Variables.

    AspectStorage VariablesSSA Variables
    Access APIfunc.getLocalVariables()LocalSymbolMap.getSymbols()
    Example Nameslocal_c, param_1dVar12, uVar3, bVar1
    Rename APIvariable.setName()HighFunctionDBUtil.updateDBVariable()
    Appears InSymbol tree, metadataDecompiled code
    PurposeTrack storage allocationPresent readable pseudocode

    Crucial Note: If your goal is to rename variables that appear in the decompiled pseudocode (the output seen by users), you must use the SSA Variables system.

  11. Perform a portable installation of VC6 SP6

    main

    Use this procedure to bypass the InstallShield flow and avoid registration failures on modern Windows. This method extracts files directly from ISOs and the SP6 self-extractor into C:\VC6\.

    Critical Requirement: You must apply the Processor Pack C2.DLL (from vcpp5.exe) after extracting SP6 files. Without this, you will encounter a fatal error C1900: Il mismatch because SP6's C1 front-end is incompatible with the base CD's C2 back-end.

    # 1. Extract the VC98 tree + helper DLLs from CD1
mkdir -p /c/VC6 && cd /c/VC6
7z x /d/vc6-sp6-ent/en_vs6_ent_cd1.iso \
    "VC98" \
    "COMMON/MSDEV98/BIN/MSPDB60.DLL" \
    "COMMON/MSDEV98/BIN/MSDIS110.DLL" \
    "COMMON/MSDEV98/BIN/MSOBJ10.DLL" -y

# 2. Copy helper DLLs into VC98/Bin so cl.exe finds them alongside itself
cp /c/VC6/COMMON/MSDEV98/BIN/MSPDB60.DLL /c/VC6/VC98/Bin/
cp /c/VC6/COMMON/MSDEV98/BIN/MSDIS110.DLL /c/VC6/VC98/Bin/
cp /c/VC6/COMMON/MSDEV98/BIN/MSOBJ10.DLL /c/VC6/VC98/Bin/

# 3. Extract the SP6 self-extractor + its inner CABs
mkdir -p /c/tmp/sp6_extract
7z x /d/vc6-sp6-ent/en_vs6_sp6.exe -o/c/tmp/sp6_extract -y
mkdir -p /c/tmp/sp6_files
for n in 1 2 3 4; do
    7z x /c/tmp/sp6_extract/VS6sp6$n.cab -o/c/tmp/sp6_files -y
done

# 4. Overlay SP6-patched files onto C:\VC6\VC98\
cp -rf /c/tmp/sp6_files/vc98/bin/.     /c/VC6/VC98/Bin/
cp -rf /c/tmp/sp6_files/vc98/include/. /c/VC6/VC98/Include/
cp -rf /c/tmp/sp6_files/vc98/lib/.     /c/VC6/VC98/Lib/

# 5. CRITICAL: apply the Processor Pack C2.DLL to fix the SP6 C1/C2 mismatch
7z x /d/vc6-sp6-ent/vcpp5.exe -o/c/tmp/vcpp5 -y
cp /c/tmp/vcpp5/c2.dll /c/VC6/VC98/Bin/C2.DLL

# 6. Verify
/c/VC6/VC98/Bin/cl.exe   # should print "Version 12.00.8804 for 80x86"

  12. Hard constraints for documenting global variables

    main

    When performing the 'Document One Global Variable' task, adhere to these strict constraints:

    • One global only: Do not attempt to touch multiple addresses in a single task.
    • No analyze_function_completeness: This tool is for functions only. Use the audit_global issues count to score globals.
    • No set_plate_comment on data: This tool requires a function target. Use batch_set_comments to apply plate comments to global addresses.
    • No decompile_function on globals: Attempting to decompile a global address will return an error and waste tool budget.
    • Skip OS/System labels: Do not rename recognized OS or library symbols (e.g., ExceptionList, StackBase, SubSystemTib, PEB, Teb*, or addresses in ffdf**** / 7ffe**** ranges). If encountered, report as Blocked: OS/system label.
    • Do not delete or refactor data: If the type or layout is incorrect and cannot be expressed via set_global, leave it unchanged and report the blocker.