🔍 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