A Lightweight MCP Server and devcontainer for AI Assisted Binary Diffing

An MCP server that runs Ghidra headless (or inside the Ghidra GUI) and gives an AI agent a small set of native Ghidra tools: listing functions and segments, searching strings, decompiling, disassembling, and following cross-references. In the workshop you and your agent add more tools to it.

Start with SETUP.md to set up for the workshop, and see AGENTS.md for how a tool is put together.

Prerequisites

mise provides Python 3.13 in a project-local virtual environment (.venv). The package itself supports Python 3.11–3.14; 3.13 is pinned because pyghidra's JPype dependency ships prebuilt wheels up to 3.13. Nothing is installed or configured outside the project directory.

Related MCP server: Ghidra MCP Bridge

How It Works

Finding Ghidra

pyghidra locates Ghidra through GHIDRA_INSTALL_DIR and the JDK through JAVA_HOME, both set by mise from mise.local.toml. The server fails to start with a clear error if either path is wrong.

Loading a Binary and Running Analysis

Pass one or more binary paths as positional arguments on startup:

ghidra-mcp /path/to/binary [/path/to/another ...]

What happens internally:

1. pyghidra.start() initialises the Ghidra JVM (loads Ghidra's JAR files into the Python process via JPype).

2. A Ghidra project is created or opened at --project-path / --project-name (defaults: ./ghidra_projects/my_project).

3. Each binary is imported into the project via GhidraProject.importProgram() and saved. Binaries are named <filename>-<sha1[:6]> to allow the same filename from different paths.

4. Ghidra auto-analysis (analyzeAll) runs in a background thread. The server answers the MCP handshake immediately; a tool call for a binary that is still being analyzed fails with [retry_later].

5. The Ghidra project is persisted to disk. On the next startup with the same --project-path, already-analyzed binaries are re-opened instantly, with no re-analysis.

By default, a tool call for a binary that is still being analyzed waits up to 45 s for it, then fails with [retry_later], saying how long analysis has been running or where the binary is in the queue. To fail straight away instead:

ghidra-mcp --no-wait-for-analysis /path/to/binary

Large binaries (Go binaries in particular) can take many minutes to analyze. Pre-analyze them once, then every later start serves them instantly:

ghidra-mcp --analyze-only /path/to/binary   # exits non-zero if any binary failed

Quick Start

Run these from the project directory (mise run serve and mise run gui pass their arguments to ghidra-mcp):

# Import, analyze, and serve a binary over stdio
mise run serve /path/to/target_binary

# Serve over HTTP (useful for remote VMs)
mise run serve --transport streamable-http --host 0.0.0.0 --port 8000 /path/to/target_binary

# Open an existing Ghidra project without importing anything
mise run serve --project-path /path/to/existing_project.gpr

# List what's already in the project
mise run serve --project-path ~/ghidra_projects --list-project-binaries

# Analyze ahead of time without serving
mise run serve --analyze-only /path/to/target_binary

# GUI mode: open the Ghidra GUI and serve alongside it (see GUI Mode)
mise run gui --project-path ~/ghidra_projects /path/to/target_binary

MCP Client Configuration

There are two deployment patterns:

• Local — the MCP client launches the server as a subprocess on the same machine (stdio transport). Use this for desktop RE work.

• Remote — the server runs on a VM or container (streamable-http transport). The MCP client connects over HTTP. Use this for cloud-based headless analysis (e.g. a t3.small).

A client launches the server outside your shell, so local configurations run it through mise: mise exec -C /path/to/this/repo -- ghidra-mcp … applies the project's Python environment and the paths in mise.local.toml. Use absolute paths. If the client cannot find mise (for example, an editor started from the Dock), give its full path instead, such as /opt/homebrew/bin/mise (see which mise).

Claude Code

Config file: ~/.claude/settings.json

Local (stdio):

{
  "mcpServers": {
    "ghidra": {
      "command": "mise",
      "args": [
        "exec", "-C", "/path/to/this/repo", "--",
        "ghidra-mcp", "--project-path", "/path/to/ghidra_projects", "/path/to/target_binary"
      ]
    }
  }
}

Remote VM (streamable-http):

Start the server on the VM, from the project directory:

mise run serve --transport streamable-http --host 0.0.0.0 --port 8000 /path/to/binary

Configure Claude Code to connect:

{
  "mcpServers": {
    "ghidra": {
      "type": "http",
      "url": "http://<vm-ip>:8000/mcp"
    }
  }
}

Add via CLI:

# stdio
claude mcp add ghidra -- mise exec -C /path/to/this/repo -- ghidra-mcp --project-path /path/to/ghidra_projects /path/to/binary

# remote HTTP
claude mcp add --transport http ghidra http://<vm-ip>:8000/mcp

GitHub Copilot (VS Code)

Create or edit .vscode/mcp.json in your workspace:

Local (stdio):

{
  "servers": {
    "ghidra": {
      "type": "stdio",
      "command": "mise",
      "args": [
        "exec", "-C", "/path/to/this/repo", "--",
        "ghidra-mcp", "--project-path", "/path/to/ghidra_projects", "/path/to/target_binary"
      ]
    }
  }
}

Remote VM (HTTP):

{
  "servers": {
    "ghidra": {
      "type": "http",
      "url": "http://<vm-ip>:8000/mcp"
    }
  }
}

For a user-level (not workspace) config, add the same block under "mcp" in VS Code's settings.json:

{
  "mcp": {
    "servers": {
      "ghidra": {
        "type": "stdio",
        "command": "mise",
        "args": [
          "exec", "-C", "/path/to/this/repo", "--",
          "ghidra-mcp", "--project-path", "/path/to/ghidra_projects", "/path/to/target_binary"
        ]
      }
    }
  }
}

Cline

Config file locations:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Or configure from the Cline panel: MCP Servers → Edit MCP Settings.

Local (stdio):

{
  "mcpServers": {
    "ghidra": {
      "command": "mise",
      "args": [
        "exec", "-C", "/path/to/this/repo", "--",
        "ghidra-mcp", "--project-path", "/path/to/ghidra_projects", "/path/to/target_binary"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Remote VM (HTTP):

{
  "mcpServers": {
    "ghidra": {
      "url": "http://<vm-ip>:8000/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

GUI Mode

Run the server inside the Ghidra GUI to watch the agent's work:

mise run gui --project-path ~/ghidra_projects /path/to/binary
claude mcp add --transport http ghidra http://127.0.0.1:8000/mcp   # in another terminal

--gui opens the Ghidra GUI in the server's own process with the project open, and serves MCP over streamable HTTP (--host/--port as usual). The tools work on the same in-memory programs CodeBrowser shows.

• Analysis is Ghidra's own. Imports open the program in CodeBrowser as a new, non-current tab and run Ghidra's auto-analysis there, with its progress bar and cancel button. Ghidra does not report analyzer failures to the server, so a binary whose analysis partly failed is listed as ready. Analysis you start yourself from the Analysis menu shows as analyzing. A program that was not analyzed (you cancelled, or imported it without analyzing) is failed until you analyze it in Ghidra and restart ghidra-mcp --gui.

• Three extra tools. get_current_address and get_current_function report where your cursor is in the most recently focused CodeBrowser; go_to moves CodeBrowser to a binary, address, or symbol. They exist only in GUI mode.

• You own saving. The server never saves the project in GUI mode; save from Ghidra when you want to keep its state.

• One project, one session. GUI mode serves the project it opened; if you close or switch projects in the GUI, tool calls fail until you restart ghidra-mcp --gui. Closing the Ghidra GUI stops the server. stdio is not available in GUI mode.

A Ghidra project can be open in only one process at a time, so a headless ghidra-mcp and a separately started Ghidra GUI cannot share a project; GUI mode is how to use both at once.

CLI Reference

ghidra-mcp [OPTIONS] [INPUT_PATHS]...

Environment variables: MCP_TRANSPORT, MCP_PORT, MCP_HOST, GHIDRA_INSTALL_DIR.

Tool Reference

Project Management

Navigation / Discovery

Function Lookup

Disassembly / Decompilation

Cross-References

GUI Mode Only