GhydraMCP

The REST API used by the bridge is HATEOAS-driven, meaning responses include navigational links (_links) for resource discovery.

Response Structure

All responses follow a standardized JSON format:

• Success: Includes id, instance, success: true, result, timestamp, and _links.
• Pagination: For list responses, includes size, offset, limit, and _links (containing next and prev).
• Errors: Includes id, instance, success: false, error (containing code and message), status_code, and timestamp.

{
  "id": "req-123",
  "instance": "http://localhost:8192",
  "success": true,
  "result": "...",
  "timestamp": 1712159482123,
  "_links": {
    "self": {"href": "/endpoint/current"},
    "related": [
      {"href": "/endpoint/related1", "name": "Related Resource 1"}
    ]
  }
}

GhydraMCP consists of four primary components that enable AI-driven reverse engineering:

1. Ghidra plugin: A plugin installed directly into Ghidra that exposes its capabilities over a HATEOAS REST API.
2. CLI tool (ghydra): A standalone terminal client for human interaction or scripting. It is the recommended integration path over the MCP bridge.
3. MCP bridge (Deprecated): A Python script (bridge_mcp_hydra.py) that translates Model Context Protocol (MCP) requests into API calls. Use the CLI tool instead for better performance and formatting.
4. Multiple instances: Support for connecting to multiple Ghidra windows simultaneously (using ports 8192-8447) to analyze different binaries in parallel.

Capabilities include decompilation, static analysis (XREFs, call graphs, data flow), memory manipulation, and symbol/data management (renaming, retyping, annotating).

GhydraMCP (v2.1.0+) uses a centralized plugin model where a single HTTP server runs on port 8192 within the FrontEndTool. Unlike previous versions that used multiple ports for different instances, all program data is now reachable via path-based addressing.

Key Architectural Concepts

• Single Port: Port 8192 is the only entry point. There is no port forwarding or proxying between instances.
• Path-Based Addressing: All program-specific data is accessed via the /files/{urlencoded_path}/... prefix.
• Headless Access: If a file is requested via a file-scoped endpoint but is not currently open in any Ghidra tool, the system automatically opens it headlessly using a ProgramCache.
• Tool-Scoped State: Interactive state (like cursor position or selection) is accessed via /tools/{name}/... endpoints.

The GhydraMCP HTTP API v2 uses a Hypermedia-driven interface (HATEOAS) to allow automated and AI-driven interaction with Ghidra's CodeBrowser.

Key Architectural Concepts:

• Instance-per-Program: Every program open in Ghidra has its own unique plugin instance. All resource paths (functions, symbols, etc.) are specific to the instance handling the request.
• HATEOAS: Responses include _links to facilitate resource discovery and navigation.
• Standard HTTP Verbs: Use GET for retrieval, POST for creation, PATCH for partial updates, PUT for full replacement, and DELETE for removal.
• JSON Communication: All request bodies (for POST, PUT, PATCH) and non-error responses must use application/json.

The HTTP API tests verify the Java plugin's endpoints, ensuring they return consistent JSON structures and handle errors correctly.

Steps to run:

1. Ensure Ghidra is running with the GhydraMCP plugin loaded.
2. Execute the test script:

python test_http_api.py

Note: Tests will automatically skip if Ghidra is not running or the plugin is unresponsive.

Coverage includes:

• Basic connectivity.
• Response format and JSON structure consistency.
• Presence of required fields.
• Error handling.

To set up GhydraMCP with the Cline extension:

1. Open VS Code with Cline installed.
2. Click the MCP Servers icon in the Cline interface.
3. Select the Configure tab.
4. Click Configure MCP Servers to edit cline_mcp_settings.json.
5. Add the configuration for uv or python (see examples below).
6. Restart Cline to load the server.

Note: Ensure you use absolute paths for bridge_mcp_hydra.py (e.g., /home/username/... or C:\Users\...).

{
  "mcpServers": {
    "ghydra": {
      "command": "uv",
      "args": [
        "run",
        "/ABSOLUTE_PATH_TO/bridge_mcp_hydra.py"
      ],
      "env": {
        "GHIDRA_HYDRA_HOST": "localhost"
      },
      "disabled": false
    }
  }
}

To install the Ghidra CLI in development mode, clone the repository and use pip. If you are using asdf for version management, you must reshim after installation.

# Install in development mode
cd /path/to/GhydraMCP
pip install -e .

# After installation, reshim if using asdf
asdf reshim

Before running tests for the GhydraMCP plugin or bridge, ensure your environment meets the following requirements:

• Python: Version 3.11 or higher.
• Ghidra: Must be running with the GhydraMCP plugin installed and loaded.
• Python Packages: The requests library must be installed.

Install the required package using:

pip install requests

When using the Ghidra CLI for scripts or AI agents, follow these best practices for clean output:

1. Use --json: This is the recommended path for structured data. You can pipe the output directly to tools like jq. Example: ghydra --json functions list | jq '.result[].name'
2. Automatic Color Handling: The CLI automatically disables ANSI colored output whenever stdout is not a terminal (e.g., when piped to a file or a subprocess). This prevents corruption of data like hex addresses.
3. Force Plain Text: If you want standard table output without ANSI styling in an interactive terminal, use the --no-color flag or set the NO_COLOR=1 environment variable.

Use the following settings for 5ire:

• Tool Key: ghydra
• Name: GhydraMCP
• Command: uv run /ABSOLUTE_PATH_TO/bridge_mcp_hydra.py