🔍 Ghidra MCP Server

This project lets you use Ghidra in headless mode to extract rich binary analysis data (functions, pseudocode, structs, enums, etc.) into a JSON file, and expose it to LLMs like Claude via Model Context Protocol (MCP).

It turns Ghidra into an interactive reverse-engineering backend.

---

🚀 Features

- Decompiles a binary using Ghidra headless mode
- Extracts:
- Function pseudocode, names, parameters, variables, strings, comments
- Data structures (structs), enums, and function definitions
- Outputs to ghidra_context.json
- MCP server exposes tools like:
- list_functions(), get_pseudocode(name)
- list_structures(), get_structure(name)
- list_enums(), get_enum(name)
- list_function_definitions(), get_function_definition(name)

---

⚙️ System Requirements

- macOS (tested)
- Python 3.10+
- Ghidra 11.3.1+
- Java 21 (Temurin preferred)
- MCP client (e.g. Claude Desktop)
- mcp CLI (install via pip install mcp)

---

🧪 Installation & Setup

✅ 1. Install Java 21 (REQUIRED by Ghidra 11.3.1)

brew install --cask temurin@21

Then set it:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
source ~/.zshrc

Check it:

java -version

Should say: openjdk version "21.0.x"...

---

✅ 2. Install Ghidra

Download and extract Ghidra 11.3.1

---

✅ 3. Set up the project

cd ghidra_mcp
gcc -Wall crackme.c -o crackme

---

✅ 4. Install the server via MCP CLI

mcp install main.py

This registers the MCP server so Claude or other clients can access it.

---

✅ 5. Run in dev mode (for testing)

mcp dev main.py

This enables hot reload and developer logs.

---

🛰️ Tools Available

| Tool | Description |
|------------------------------|--------------------------------------------|
| setup_context(...) | Run Ghidra on a binary |
| list_functions() | All functions |
| get_pseudocode(name) | Decompiled pseudocode |
| list_structures() | All structs |
| get_structure(name) | Details of a struct |
| list_enums() | All enums |
| get_enum(name) | Enum values |
| list_function_definitions()| All function prototypes |
| get_function_definition() | Return type & args |

---

Sample Promot

Analyze the binary file located at <BINARY_PATH> using Ghidra installed at <GHIDRA_PATH>. First, set up the analysis context using both paths, then list all functions in the binary. Examine the main entry point function and provide a high-level overview of what the program does.

🧠 Common Issues & Fixes

❌ Ghidra fails with “unsupported Java version”

➡️ Fix: Install Java 21, not 17 or 24:

brew install --cask temurin@21
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

---

❌ spawn uv ENOENT (Claude Desktop can't find your UV binary)

➡️ Claude can't locate uv by name. To fix:

1. Run in your terminal:

which uv

Example output:

/Users/yourname/.cargo/bin/uv

2. Open your Claude Desktop config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Update it like so:

{
  "mcpServers": {
    "ghidra": {
      "command": "/Users/yourname/.cargo/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/Documents/ghidra_mcp",
        "run",
        "main.py"
      ]
    }
  }
}

4. Restart Claude Desktop. You should now see your custom MCP tools.

---

❌ The operation couldn’t be completed. Unable to locate a Java Runtime.

➡️ Fix: Java not installed or JAVA_HOME is unset. Follow setup instructions above.

---

📂 Project Structure

| File | Purpose |
|---------------------|----------------------------------|
| main.py | MCP server with tools |
| export_context.py | Ghidra script that extracts JSON |
| crackme.c | Sample C binary |
| crackme | Compiled binary to test |

---

👨‍💻 Author

Tomi Bamimore
Ghidra by the NSA
MCP by Anthropic