ghidriff-mcp

An MCP server that exposes ghidriff — the Ghidra binary diffing engine — as tools an AI agent can call.

Point it at an old and a new build of a binary and it drives Ghidra headlessly through ghidriff, then hands back structured results: match statistics, added/deleted/modified functions, per-function code diffs and the generated Markdown report — as JSON, not as a screenful of console noise.

English | 简体中文

Contents

• Why this exists

• Requirements

• Install

• Configuration

• Tools

• How it works

• Security and trust model

• Troubleshooting

• Compared with GhidraMCP

• Project layout

• Development

• License

Related MCP server: GhidraMCP

Why this exists

ghidriff is excellent but it is a batch CLI: you invoke it, wait while Ghidra imports and analyses every input, and you get a Markdown report plus a large pdiff JSON on disk. That shape does not fit an agent loop, where you want to inspect a change, follow up on one function, and keep the reasoning in context.

This server closes that gap:

• Jobs instead of blocking calls. Every diff runs in the background with an id, a log file and a persisted job.json, so a crash or restart does not lose the result.

• Structured output. The pdiff JSON ghidriff writes is the source of truth; the server turns it into compact summaries and per-function details instead of dumping megabytes into the model's context.

• Late-bound environment. The server does not need ghidriff or Ghidra in its own interpreter — it launches whichever interpreter or command you configure.

• Honest errors. Ghidra's failure modes are translated into actionable messages: missing GHIDRA_INSTALL_DIR, a project path Ghidra refuses, a JVM out of memory, a missing pyghidra.

• A boundary you control. The agent decides what to diff; you decide how the engine runs. See Security and trust model.

Requirements

Ghidra and ghidriff do not have to live in the same interpreter as this server. If your MCP client runs the server from an isolated virtualenv, point GHIDRIFF_MCP_PYTHON at the interpreter that has ghidriff installed.

Tested against ghidriff 1.0.0, Ghidra 12.1.3 and JDK 21 on Windows, and in CI on Ubuntu, macOS and Windows with Python 3.10 and 3.13.

Install

pip install ghidriff-mcp

Or from source:

git clone https://github.com/waterofriver/ghidriff-mcp
cd ghidriff-mcp
pip install -e .

Verify the tool chain with the built-in self check:

ghidriff-mcp --check

It prints a JSON diagnosis of Ghidra, Java and ghidriff, with next steps for anything missing, and exits non-zero when the setup is not usable yet:

// ghidriff-mcp --check (trimmed for length)
{
  "ready": true,
  "checks": {
    "ghidra": { "ok": true, "detail": "Ghidra 12.1.3 at C:\\ghidra\\ghidra_12.1.3_PUBLIC (found via GHIDRA_INSTALL_DIR)" },
    "java": { "ok": true, "detail": "Java 21.0.12.1 (C:\\Program Files\\Microsoft\\jdk-21...\\bin\\java.exe)" },
    "ghidriff": { "ok": true, "detail": "ghidriff 1.0.0 importable by C:\\Python313\\python.exe" }
  },
  "problems": [],
  "next_steps": []
}

The same report is available to agents through the ghidriff_environment tool.

Configuration

Everything is environment driven.

Ghidra path rule. Ghidra refuses a project location containing a path element that starts with . (Path element starting with '.' is not permitted). Keep GHIDRIFF_MCP_HOME dot-free; if it is not, the server relocates the Ghidra project to the system temp directory and reports a warning instead of failing after a multi-minute import.

MCP client configuration

{
  "mcpServers": {
    "ghidriff": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "ghidriff_mcp"],
      "env": {
        "GHIDRA_INSTALL_DIR": "C:\\ghidra\\ghidra_12.1.3_PUBLIC",
        "GHIDRIFF_MCP_PYTHON": "C:\\Python313\\python.exe",
        "GHIDRIFF_MCP_HOME": "C:\\ghidriff-work"
      }
    }
  }
}

HTTP transports are available for clients that prefer them:

ghidriff-mcp --transport streamable-http --host 127.0.0.1 --port 8765

Command-line flags: --check (self check), --workspace PATH and --ghidra-install-dir PATH (override the matching environment variables for this process), --transport, --host, --port, --version.

Tools

Thirteen tools, all prefixed ghidriff_ so an agent can tell them apart from other Ghidra-related servers.

ghidriff_start_diff accepts old_binary, one or more new_binaries, the engine (VersionTrackingDiff, SimpleDiff, StructualGraphDiff), output_dir, project_dir, summary, side_by_side, force_analysis, force_diff, bsim, bsim_full, min_func_len, max_section_funcs, base_address, no_symbols and timeout_s. Raw engine pass-through is deliberately not on this list — that lives in GHIDRIFF_MCP_EXTRA_ARGS.

Pass several newer binaries to get chained diffs (old → v2 → v3), and set summary=true to also diff old → newest. Use side_by_side=true if you want the per-function HTML diffs on disk.

How it works

MCP client ──stdio──▶ ghidriff-mcp ──subprocess──▶ ghidriff ──PyGhidra──▶ Ghidra (JVM)
                           │                            │
                           │                            └── writes <name>.ghidriff.md
                           │                                       json/<name>.ghidriff.json
                           └── job.json + ghidriff.log              json/<name>.ghidriff.matches.json
                               (structured summaries, paged reads)

• The server never imports ghidriff, so a JVM crash cannot take it down, and cancelling a job is a single kill.

• One run directory per job: <workspace>/runs/<job_id>/ containing job.json, ghidriff.log, ghidriff/ (output) and ghidra_projects/.

• Child output is redirected into the log file through an inherited handle rather than a pipe, which keeps it streamable and works in environments where pipes are restricted.

• pdiff JSON files are parsed lazily, capped in size and cached by mtime.

• Relative paths in tool calls resolve against the workspace, so an agent never has to know the absolute layout of the machine.

Security and trust model

This server drives ghidriff locally with your own privileges on files you point it at. Before wiring it to an agent, know what it does and does not constrain:

• No shell. Every command is an argv list built by the server and passed to exec-style process creation. Nothing is interpolated into a shell string, so file names and option values cannot become shell syntax.

• The agent picks the target, you pick the engine. Tool arguments select which binaries to diff, which supported engine to use, and how much output to render. They cannot select the executable, its JVM arguments, or arbitrary extra CLI switches. That matters, because --jvm-args -javaagent:... would otherwise be a code-execution primitive one model decision away.

• Option-like file names are neutralised. Binaries are passed after a -- separator, so a file named --force-analysis stays a file.

• Binaries are untrusted input. Strings, symbol names, decompiled code and report text from a sample end up in the model's context. Treat all of it as data, never as instructions: a crafted binary can try to talk your agent into something. The same holds for anything else you feed the model.

• Symbol lookups reach the network by default. ghidriff lets Ghidra resolve PDBs, and for PE files with PDB metadata that can mean a query to a symbol server (Microsoft's among them), which leaks a little about what you are analysing. Pass no_symbols=true, or set GHIDRIFF_MCP_EXTRA_ARGS=--no-symbols, for offline work.

• File access is not confined. The server reads and writes wherever you point it, because binaries normally live outside the workspace. Use a dedicated workspace and do not hand an agent paths to files you would not want in a transcript.

• Transports. stdio by default. The HTTP transports bind to 127.0.0.1 unless you pass --host, and they carry no authentication — treat a non-loopback bind as exposing the server to that network.

• External tooling is the real attack surface. Ghidra parsing a hostile file is a much bigger risk than this wrapper. Keep ghidriff and Ghidra current, and run samples in a VM you can throw away.

Everything a run produces lives under GHIDRIFF_MCP_HOME, so that directory is the thing to review — and delete — when you are done.

Troubleshooting

Compared with GhidraMCP

GhidraMCP bridges a running Ghidra GUI to an agent: interactive decompilation, renaming, commenting. This server does the opposite job: batch, headless diffing between two builds, with no GUI and no open project. They complement each other, and the ghidriff_ prefix means an agent can use both at once.

Project layout

src/ghidriff_mcp/
  server.py      FastMCP tool surface and CLI entry point
  runner.py      ghidriff command construction and subprocess execution
  jobs.py        background job state machine, job.json persistence
  reports.py     pdiff / Markdown parsing, paging, size limits
  ghidra_env.py  Ghidra, Java and ghidriff discovery and diagnosis
  paths.py       workspace path resolution and Ghidra path rules
  config.py      environment-driven settings
tests/           unit, protocol-level and opt-in integration tests

Development

pip install -e ".[dev]"
pytest                       # 110 tests, no Ghidra needed
ruff check src tests
ruff format --check src tests

The Ghidra-dependent test is opt-in:

GHIDRIFF_MCP_INTEGRATION=1 GHIDRA_INSTALL_DIR=/path/to/ghidra pytest -m integration

It generates a pair of PE files (a pristine copy of a system binary and one whose entry point is patched) and asserts that at least one function is reported as modified.

License

MIT — see LICENSE.

This project contains no ghidriff source code and does not link against it. It invokes ghidriff (GPL-3.0) and Ghidra (Apache-2.0) as separate processes that you install yourself; those programs keep their own licenses.