Ghidra Headless MCP Server

Ghidra Headless MCP

A headless Ghidra server that speaks MCP (Model Context Protocol), giving AI agents full access to deep reverse-engineering workflows: program lifecycle, disassembly, decompilation, patching, types, xrefs, scripting, and more, without a GUI.

Designed to run in the same Docker container as the agent runtime. No sidecars, no extra services.

This entire project---code, tests, and documentation---is 100% vibe coded.

Why

Existing Ghidra automation usually assumes either interactive GUI use or ad hoc scripts with a narrow workflow. This server is headless-only and designed for agent-driven workflows in sandboxed VM/container environments: the agent gets full control over the analysis system, automating large parts of reverse engineering while you interactively discuss and steer the process.

The goal is an interface where agents can inspect, refine, and extend an analysis over time: updating types, symbols, and metadata, improving the analysis database incrementally, applying patches and iterating safely with transactions and undo/redo, and running custom scripts when a workflow needs something bespoke.

Features

• 212 tools across 34 feature groups: project and program lifecycle, disassembly, decompilation, patching, transactions, types, layouts, memory, search, graph extraction, scripting, and more.
• Read-only by default with safe mutation workflows (transactions, undo/redo, explicit save paths).
• Scripting access via ghidra.eval, ghidra.call, and ghidra.script for anything the tool catalog doesn't cover.
• Stdio and TCP transports.
• Real pyghidra backend for live headless Ghidra workflows.
• Fake backend mode for CI and development without a Ghidra install.

Prerequisites

• Python 3.11+
• A Ghidra installation plus pyghidra in your runtime (for real analysis)
• For CI/development without Ghidra, use fake backend mode

Installation

From the repo root:

python3 -m venv .venv
. .venv/bin/activate
pip install .

For development:

pip install -e ".[dev]"

Quick Start

Stdio transport (default):

GHIDRA_INSTALL_DIR=/ABSOLUTE/PATH/TO/ghidra python3 ghidra_headless_mcp.py

TCP transport:

GHIDRA_INSTALL_DIR=/ABSOLUTE/PATH/TO/ghidra python3 ghidra_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765

Fake backend mode (no Ghidra required):

python3 ghidra_headless_mcp.py --fake-backend

Installed console script:

ghidra-headless-mcp --version

Use With AI Agents

This server speaks standard MCP over stdio (default) or tcp, so any MCP-capable agent host can use it.

Claude Code

claude mcp add ghidra_headless_mcp -- python3 /path/to/ghidra-headless-mcp/ghidra_headless_mcp.py --ghidra-install-dir /ABSOLUTE/PATH/TO/ghidra

Or add it to your project's .mcp.json:

{
  "mcpServers": {
    "ghidra_headless_mcp": {
      "command": "python3",
      "args": [
        "ghidra_headless_mcp.py",
        "--ghidra-install-dir",
        "/ABSOLUTE/PATH/TO/ghidra"
      ],
      "cwd": "/path/to/ghidra-headless-mcp"
    }
  }
}

For fake mode, append --fake-backend and omit the install dir.

Codex

codex mcp add ghidra_headless_mcp -- python3 ghidra_headless_mcp.py --ghidra-install-dir /ABSOLUTE/PATH/TO/ghidra

Generic MCP Host

• Register a server named ghidra_headless_mcp.
• Use command python3 with args ["ghidra_headless_mcp.py", "--ghidra-install-dir", "/ABSOLUTE/PATH/TO/ghidra"] when cwd is the repo root, or use an absolute script path in args.
• Set cwd to the repo path if you want relative paths like samples/ls to resolve correctly.
• Use stdio transport unless your host requires TCP.
• For fake mode (no Ghidra installed), append --fake-backend.
• Verify connectivity by calling health.ping, then program.open.

Docker Co-Location Pattern

Recommended deployment model: run the agent process and this MCP server in the same container image.

Example baseline:

FROM kalilinux/kali-rolling:latest
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip ghidra
WORKDIR /app
COPY . /app
RUN python3 -m pip install --upgrade pip --break-system-packages \
 && python3 -m pip install ".[dev]" --break-system-packages
CMD ["python3", "ghidra_headless_mcp.py", "--fake-backend"]

If you need real Ghidra analysis in-container, keep Ghidra installed in that same image and set GHIDRA_INSTALL_DIR or pass --ghidra-install-dir.

MCP Methods

• initialize
• ping
• tools/list
• tools/call
• shutdown

tools/list behavior:

• Without explicit pagination params, returns the full tool catalog.
• If offset or limit is provided, uses paginated output (offset=0, limit=50 default in paged mode).
• Supports filtering via:
  • prefix (for example `p