A production-ready Model Context Protocol (MCP) server that bridges Ghidra's powerful reverse engineering capabilities with modern AI tools and automation frameworks. 251 MCP tools, battle-tested AI workflows, and the most comprehensive Ghidra-MCP integration available — now including P-code emulation, live debugger integration, and PCode-graph data flow analysis. Most Ghidra MCP implementations g
npx mdskills install bethington/ghidra-mcp@bethington? Sign in with GitHub to claim this listing.Production-grade Ghidra integration with 251 tools, emulation, debugging, and battle-tested AI workflows
1# Ghidra MCP Server23[](https://mcptoplist.com/server/glama%2Fbethington%2Fghidra-mcp)45[](https://github.com/bethington/ghidra-mcp/actions/workflows/tests.yml)6[](https://github.com/bethington/ghidra-mcp/releases/latest)7[](LICENSE)8[](https://github.com/sponsors/bethington)910[](https://www.python.org/)11[](https://openjdk.org/projects/jdk/21/)12[](https://ghidra-sre.org/)13[](https://modelcontextprotocol.io/)1415[](https://github.com/bethington/ghidra-mcp/stargazers)16[](https://github.com/bethington/ghidra-mcp/commits/main)17[](https://github.com/bethington/ghidra-mcp/discussions)18[](https://github.com/bethington/ghidra-mcp/issues)19[](https://scorecard.dev/viewer/?uri=github.com/bethington/ghidra-mcp)2021> If you find this useful, please ⭐ star the repo — it helps others discover it!22>23> If Ghidra MCP saves you time, consider [sponsoring the project](https://github.com/sponsors/bethington). One-time and recurring support both help fund compatibility updates, production hardening, docs, and new tooling.2425A production-ready Model Context Protocol (MCP) server that bridges Ghidra's powerful reverse engineering capabilities with modern AI tools and automation frameworks. **251 MCP tools**, battle-tested AI workflows, and the most comprehensive Ghidra-MCP integration available — now including P-code emulation, live debugger integration, and PCode-graph data flow analysis.2627## Why Ghidra MCP?2829Most Ghidra MCP implementations give you a handful of read-only tools and call it a day. This project is different — it was built by a reverse engineer who uses it daily on real binaries, not as a demo.3031- **251 MCP tools** — 3x more than any competing implementation. Not just read operations — full write access for renaming, typing, commenting, structure creation, script execution, P-code emulation, and live debugging.32- **Battle-tested AI workflows** — Proven documentation workflows (V5) refined across hundreds of functions. Includes step-by-step prompts, Hungarian notation reference, batch processing guides, and orphaned code discovery.33- **Production-grade reliability** — Atomic transactions, batch operations (93% API call reduction), configurable timeouts, and graceful error handling. No silent failures.34- **Cross-binary documentation transfer** — SHA-256 function hash matching propagates documentation across binary versions automatically. Document once, apply everywhere.35- **Full Ghidra Server integration** — Connect to shared Ghidra servers, manage repositories, version control, checkout/checkin workflows, and multi-user collaboration.36- **Headless and GUI modes** — Run with or without the Ghidra GUI. Docker-ready for CI/CD pipelines and automated analysis at scale.37- **Opinionated by design** — v5.0 moves naming conventions, type safety, and documentation standards into the tool layer. AI agents and human engineers produce consistent output without style guides in every prompt.3839## Convention Enforcement4041You've been there: six months into a project you find `ProcessItem`, `process_items`, `handleItem`, and `ItemProc` in the same codebase — four functions doing the same thing, named by four different sessions or engineers with no shared contract. Fixing it takes longer than it should, and the problem will happen again.4243v5.0 moves conventions from "things to remember" into the tool layer, where they can actually be enforced.4445| Tier | Behavior | Example |46|------|----------|---------|47| **Auto-fix** | Applied silently | `count` field on a `uint32` → auto-prefixed `dwCount` on save |48| **Warn** | Change goes through, warning returned | `processData` → "name should be PascalCase with a verb: `ProcessData`" |49| **Reject** | Change blocked with explanation | `undefined → undefined` type change → "no-op rejected, type unchanged" |5051**For AI agents**, this means consistent output across every session, every model, every run — without pasting a style guide into every prompt. The tool knows the rules; the model just needs to make the call.5253**For teams**, it eliminates the entire class of review comment that says "that's not our naming convention." Convention arbitration stays in the tool, not in code review.5455**For solo work at scale**, `analyze_function_completeness` gives you a 0–100% score that measures honestly: structural deductions (unfixable compiler artifacts) are forgiven in your effective score, log-scaling prevents one bad category from burying everything else, and tiered plate comment quality means you know exactly what's missing and why.5657## 🌟 Features5859### Core MCP Integration60- **Full MCP Compatibility** — Complete implementation of Model Context Protocol61- **251 MCP tools** — Comprehensive API surface covering every aspect of binary analysis62- **Production-Ready Reliability** — Atomic transactions, batch operations, configurable timeouts63- **Real-time Analysis** — Live integration with Ghidra's analysis engine6465> **Compatibility note:** MCP tool names are normalized for GitHub Copilot CLI66> and CAPI validation. Exposed tool names use lowercase letters, digits,67> underscores, and hyphens only; nested HTTP paths such as `/debugger/status`68> are advertised as names like `debugger_status_2` when needed to avoid69> collisions with static bridge tools.7071### Binary Analysis Capabilities72- **Function Analysis** — Decompilation, call graphs, cross-references, completeness scoring73- **Data Flow Analysis** — PCode-graph value propagation (forward / backward) from any variable or register74- **Data Structure Discovery** — Struct/union/enum creation with field analysis and naming suggestions75- **String Extraction** — Regex search, quality filtering, and string-anchored function discovery76- **Import/Export Analysis** — Symbol tables, external locations, ordinal import resolution77- **Memory & Data Inspection** — Raw memory reads, byte pattern search, array boundary detection78- **Cross-Binary Documentation** — Function hash matching and documentation propagation across versions7980### Dynamic Analysis (v5.4.0)81- **P-code Emulation** — Run any function in isolation via Ghidra's `EmulatorHelper`; brute-force API hash resolution in milliseconds82- **Live Debugger Integration** — 17 Java endpoints + 22 Python bridge tools over Ghidra's TraceRmi framework (dbgeng on Windows PE, gdb/lldb otherwise): attach, step, breakpoints, registers, memory reads, non-breaking function tracing, ASLR-aware static↔dynamic address translation8384### AI-Powered Reverse Engineering Workflows85- **Function Documentation Workflow V5** — 7-step process for complete function documentation with Hungarian notation, type auditing, and automated verification scoring86- **Batch Documentation** — Parallel subagent dispatch for documenting multiple functions simultaneously87- **Orphaned Code Discovery** — Automated scanner finds undiscovered functions in gaps between known code88- **Data Type Investigation** — Systematic workflows for structure discovery and field analysis89- **Cross-Version Matching** — Hash-based function matching across different binary versions9091### Development & Automation92- **Ghidra Script Management** — Create, run, update, and delete Ghidra scripts entirely via MCP93- **Multi-Program Support** — Switch between and compare multiple open programs94- **Batch Operations** — Bulk renaming, commenting, typing, and label management (93% fewer API calls)95- **Headless Server** — Full analysis without Ghidra GUI — Docker and CI/CD ready96- **Project & Version Control** — Create projects, manage files, Ghidra Server integration97- **Analysis Control** — List, configure, and trigger Ghidra analyzers programmatically9899## 🚀 Quick Start100101### Prerequisites102103- **Java 21 LTS** (OpenJDK recommended)104- **Apache Maven 3.9+**105- **Ghidra 12.1.2** (or compatible version)106- **Python 3.10+** with [uv](https://docs.astral.sh/uv/) (recommended) or pip + venv107108> Shared Ghidra Server users: Ghidra 12.1.2 clients require a Ghidra109> Server at 12.1, 12.0.5, or a newer compatible version. Upgrade the110> server before using this plugin from a 12.1 client.111>112> Ghidra 12.1.2 ships Jython as an optional extension. Java scripts work113> by default, but `.py` scripts in `ghidra_scripts/` require installing114> the Jython extension from **File > Install Extensions** and restarting115> Ghidra.116117### Installation118119> Recommended for all platforms: use `python -m tools.setup` directly.120>121> `ensure-prereqs` installs runtime Python requirements plus the Ghidra JARs needed in the local Maven repository.122> `deploy` copies the build output, installs the user-profile extension, and patches Ghidra user config.1231241. **Clone the repository:**125 ```bash126 git clone https://github.com/bethington/ghidra-mcp.git127 cd ghidra-mcp128 ```1291302. **Recommended: run environment preflight first:**131 ```text132 python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"133 ```1341353. **Build and deploy to Ghidra:**136 ```text137 python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC"138 python -m tools.setup build139 python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"140 ```141142 `deploy` saves/closes an already-running matching Ghidra instance when143 needed, installs the extension, starts Ghidra, waits for MCP health, and runs144 schema smoke checks.1451464. **Optional strict/manual mode** (advanced):147 ```text148 # Skip automatic prerequisite setup149 python -m tools.setup build150 python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"151 ```1521535. **Show command help**:154 ```text155 python -m tools.setup --help156 ```1571586. **Optional build-only mode** (advanced/troubleshooting):159 ```text160 python -m tools.setup build161 ```162163 Supported build path: `python -m tools.setup build` uses Maven under the hood and is the canonical workflow used by the repo tasks and docs.164165 ```bash166 # Manual Maven build (requires Ghidra deps already installed in local .m2)167 mvn clean package assembly:single -DskipTests168 ```169170 ```bash171 # Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)172 GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension173 ```174175### Installation (Linux — Ubuntu/Debian)1761771. **Clone the repository:**178 ```bash179 git clone https://github.com/bethington/ghidra-mcp.git180 cd ghidra-mcp181 ```1821832. **Install system prerequisites** (if not already installed):184 ```bash185 sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip186 ```187188 > **Debian/Kali/Ubuntu 23.04+ note (PEP 668):** these distros mark the system189 > Python as *externally managed*, so a bare `pip install` fails with190 > `error: externally-managed-environment`. Don't work around it with191 > `--break-system-packages` — it can corrupt apt-managed tooling. Instead use192 > [uv](https://docs.astral.sh/uv/) (recommended — it creates and manages a193 > project-local `.venv` automatically, and is what this repo's commands use):194 > ```bash195 > curl -LsSf https://astral.sh/uv/install.sh | sh196 > uv run bridge-mcp-ghidra # resolves deps into .venv and starts the bridge197 > ```198 > or a classic virtual environment:199 > ```bash200 > python3 -m venv .venv && source .venv/bin/activate201 > pip install -e .202 > bridge-mcp-ghidra203 > ```2042053. **Run environment preflight:**206 ```bash207 python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC208 ```2092104. **Build and deploy to Ghidra (single command):**211 ```bash212 python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC213 python -m tools.setup build214 python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC215 ```216217 This will:218 - Install Ghidra JAR dependencies into your local `~/.m2/repository`219 - Build `GhidraMCP-<version>.zip` with Maven220 - Extract the extension to `~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/`221 - Update `preferences` with `LastExtensionImportDirectory`222 - Install Python requirements2232245. **Optional: setup only Maven dependencies:**225 ```bash226 python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC227 ```2282296. **Show command help:**230 ```bash231 python -m tools.setup --help232 ```233234> **Linux paths:** The extension is installed to `$HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/`.235> Ghidra config files are in `$HOME/.config/ghidra/ghidra_<version>_PUBLIC/`.236237### Installation (macOS — Homebrew)2382391. **Install prerequisites:**240 ```bash241 brew install openjdk@21 maven python ghidra242 ```2432442. **Clone the repository:**245 ```bash246 git clone https://github.com/bethington/ghidra-mcp.git247 cd ghidra-mcp248 ```2492503. **Install Ghidra JARs into local Maven:**251 ```bash252 python -m tools.setup install-ghidra-deps \253 --ghidra-path /opt/homebrew/opt/ghidra/libexec254 ```2552564. **Build and deploy:**257 ```bash258 python -m tools.setup ensure-prereqs \259 --ghidra-path /opt/homebrew/opt/ghidra/libexec260 python -m tools.setup build261 python -m tools.setup deploy \262 --ghidra-path /opt/homebrew/opt/ghidra/libexec263 ```264 The extension is installed to `~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/`.265266 > **Note:** `--ghidra-version` is required when using the Homebrew path because the path contains no version string.2672685. **Start Ghidra and enable the plugin:**269 ```bash270 /opt/homebrew/opt/ghidra/libexec/ghidraRun271 ```272 In the main project window: **Tools > GhidraMCP > Start MCP Server**2732746. **Configure Cursor/Claude MCP** (`~/.cursor/mcp.json`):275 ```json276 {277 "mcpServers": {278 "ghidra": {279 "command": "uv",280 "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"]281 }282 }283 }284 ```285286### Installation (Arch Linux — AUR)287288[@Pandoriaantje](https://github.com/Pandoriaantje) maintains community AUR packages:289290- [`ghidra-mcp-git`](https://aur.archlinux.org/packages/ghidra-mcp-git) — tracks `main`291- [`ghidra-mcp`](https://aur.archlinux.org/packages/ghidra-mcp) — tracks tagged releases292293Install with your AUR helper of choice, e.g.:294295```bash296yay -S ghidra-mcp # or ghidra-mcp-git297```298299### Basic Usage300301#### Option 1: Stdio Transport (Recommended for AI tools)302```bash303uv run bridge-mcp-ghidra # or: python -m bridge_mcp_ghidra304```305306To add the bridge to [Autohand Code](https://github.com/autohandai/code-cli/) from a cloned checkout:307308```bash309autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra310```311312Add `--scope project` before `ghidra` to save the server in the current project's `.autohand` configuration instead of your user configuration.313314#### Option 2: Streamable HTTP Transport (Recommended for web/HTTP clients)315```bash316uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081317```318319MCP client config for the HTTP transport (add to your client's MCP config file):320```json321{322 "mcpServers": {323 "ghidra-mcp-http": {324 "url": "http://127.0.0.1:8081/mcp"325 }326 }327}328```329330Browser-based clients (e.g. [MCP Inspector](https://github.com/modelcontextprotocol/inspector))331work out of the box: the HTTP transports answer CORS preflight (`OPTIONS`) requests and expose332the `mcp-session-id` / `mcp-protocol-version` headers to scripts. Allowed origins mirror the333Host-header policy — loopback on any port is always permitted, plus the bind host and any334hosts listed in `GHIDRA_MCP_ALLOWED_HOSTS`.335336#### Option 3: SSE Transport (Deprecated — use streamable-http instead)337```bash338uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081339```340341#### Bridge advanced flags342343| Flag | Default | Description |344|------|---------|-------------|345| `--transport` | `stdio` | `stdio` (AI tools), `streamable-http` (web clients), `sse` (deprecated) |346| `--mcp-host` | `127.0.0.1` | Bind host for HTTP transports |347| `--mcp-port` | — | Port for HTTP transports |348| `--lazy` | off | Load only the default tool groups on connect. Faster startup, but MCP clients that don't support `tools/list_changed` will see an incomplete tool list. Not recommended for Claude Code. |349| `--no-lazy` | (default) | Load all tool groups immediately on connect. Required for most AI clients. |350| `--default-groups` | `listing,function,program` | Comma-separated groups loaded on connect when `--lazy` is set. |351352#### Strict program routing (multi-program safety)353354Set `GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1` to make the bridge refuse any program-scoped355call that omits a program selector, returning a clear error instead of letting the call356ride the server's shared "current program" (the one `switch_program` and the357active GUI tab move).358359```bash360export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1361uv run bridge-mcp-ghidra362```363364Without this, a call that leaves `program=` out runs against whichever program365is current, which is fine for a single-program workflow but a hazard once366several programs are open: the call can read or edit the wrong binary with no367error. The hazard is worse when more than one client shares a server, since368each one moves that current-program global out from under the others.369370With strict mode on, every program-scoped call must name its target. This371covers every selector that picks an open program: plain `program=` and the372cross-program tools' `source_program`/`target_program` or `program_a`/`program_b`373(declared required, but the server still falls back to the current program when374one arrives empty). A forgotten selector surfaces as a loud error on the first375bad call instead of a silent write to the wrong binary. Tools with no program376selector (`open_program` and `close_program` take `path`/`name`) are unaffected.377Off by default: with the variable unset the bridge sends calls unchanged.378379#### Reducing tool-context overhead380381The bridge exposes a large catalog. To keep the model's tool surface small, run382with `--lazy` (loads only `listing,function,program` on connect) and let the383model **discover** the rest on demand instead of registering everything:384385- `search_tools("rename function")` — keyword-search the **entire** catalog,386 including tools whose group isn't loaded. Each result says whether it's387 callable now and, if not, the exact `load_tool_group(...)` call to enable it.388- `list_tool_groups()` — list all categories and their load state.389- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — load or390 drop a category at runtime.391- `check_tools("rename_symbol,batch_set_comments")` — confirm specific tools392 are callable right now.393394`search_tools` works in both eager and `--lazy` modes, so agents that honor395`tools/list_changed` get full discovery without the upfront context cost.396397#### Optional: Start the standalone debugger server398```bash399uv sync --group debugger400uv run python -m debugger401```402403The debugger server listens on `http://127.0.0.1:8099/` by default and is404required for the `debugger_*` proxy tools exposed by the MCP bridge.405406Debugger server flags:407408| Flag | Default | Description |409|------|---------|-------------|410| `--port` | `8099` | HTTP server port |411| `--host` | `127.0.0.1` | Bind address (`0.0.0.0` to expose on LAN) |412| `--exports-dir` | — | Path to a `dll_exports/` directory for ordinal-to-name resolution |413| `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, or `ERROR` |414415Set `GHIDRA_DEBUGGER_URL` in `.env` if you change the default port or host so the bridge can find it.416417#### In Ghidra4181. Start Ghidra and open a **CodeBrowser** window4192. In **CodeBrowser**, enable the plugin via **File > Configure > Configure All Plugins > GhidraMCP**4203. Optional: configure custom port via **CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server**4214. Start the server via **Tools > GhidraMCP > Start MCP Server**4225. The server runs on `http://127.0.0.1:8089/` by default423424#### Verify It's Working425```bash426# Quick health check427curl http://127.0.0.1:8089/check_connection428# Expected: "Connected: GhidraMCP plugin running with program '<name>'"429430# Get version info431curl http://127.0.0.1:8089/get_version432```433434## Support This Project435436If Ghidra MCP saves you engineering or reverse-engineering time, consider [sponsoring the project](https://github.com/sponsors/bethington).437438- One-time sponsorship helps fund fixes, compatibility updates, and release work.439- Recurring sponsorship helps keep maintenance, docs, and production hardening moving.440- Company support helps prioritize long-term reliability for the bridge, headless server, debugger integration, and workflow tooling.441442## 🔒 Security443444GhidraMCP is designed for **localhost-only development**. The default configuration — HTTP server bound to `127.0.0.1`, no authentication — is safe on a trusted single-user workstation and matches pre-v5.4.1 behavior.445446**If you expose the server beyond loopback, configure these three environment variables first.** The server refuses to start on a non-loopback bind without a token.447448| Env var | Effect |449|---|---|450| `GHIDRA_MCP_AUTH_TOKEN` | When set, every HTTP request must carry `Authorization: Bearer <token>`. Timing-safe comparison. `/mcp/health`, `/health`, `/check_connection` are exempt. |451| `GHIDRA_MCP_ALLOW_SCRIPTS` | Set to `1`, `true`, or `yes` to enable `/run_script_inline` and `/run_ghidra_script`. **Off by default as of v5.4.1** — these endpoints execute arbitrary Java against the Ghidra process. In headless mode this also triggers OSGi `BundleHost` initialization at server startup (Felix framework, ~hundreds of ms); leave it off if you don't need script execution. |452| `GHIDRA_MCP_FILE_ROOT` | When set to a directory path, filesystem-path endpoints (`/load_program`, `/import_file`, `/open_project`, `/delete_file`, etc.) canonicalize the input and require it to fall under this root. Prevents path-traversal. |453454Name-quality enforcement is separate from security. By default,455`rename_function` and global write endpoints reject names that fail456the built-in quality gates, and struct field writes apply the built-in field457prefix convention. Disable the built-in convention layer with **Edit > Tool458Options > GhidraMCP HTTP Server > Strict Naming Enforcement**. The same Tool459Options checkbox covers `rename_symbol` (all symbol kinds),460`set_global`, the `apply_data_type` prefix/type guard, and struct-field461Hungarian prefix auto-fixes in `create_struct`, `add_struct_field`, and462`modify_struct_field`. The setting is read when the MCP server starts or463restarts. Function/global convention warnings are still returned when464enforcement is disabled.465466### Example: exposing to a private LAN with auth467468```bash469export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)470export GHIDRA_MCP_ALLOW_SCRIPTS=1 # only if your workflow needs it471export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs472473java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089474```475476### Ghidra Server authentication477478When connecting to a shared Ghidra Server, GhidraMCP can suppress the password dialog automatically. It resolves credentials in this order (first non-empty value wins):479480Compatibility note: Ghidra 12.1.2 clients require Ghidra Server 12.1.2,48112.0.5, or a newer compatible server. Older shared servers are not safe482targets for a 12.1 client upgrade.4834841. `GHIDRA_SERVER_PASSWORD` environment variable (or `.env` file in the Ghidra install directory or `~`)4852. `~/.ghidra-cred` — single-line password file in your home directory4863. `<ghidra-install-dir>/.ghidra-cred`487488Username resolves similarly: `GHIDRA_SERVER_USER` env var → `user.name` system property.489490If no password is found, Ghidra shows its normal GUI prompt. Set these in `.env` (see `.env.template` for the full block) to enable silent auth.491492### Migration from v5.4.0 → v5.4.1493494- **Script endpoints now default-off.** If you relied on `/run_script_inline` or `/run_ghidra_script`, export `GHIDRA_MCP_ALLOW_SCRIPTS=1`. This is a deliberate breaking change; the prior default was unsafe.495- **Localhost-only deployments need no changes.** Auth, bind refusal, and path-root checks are all opt-in.496497## ❓ Troubleshooting498499### "GhidraMCP" menu not appearing in Tools500501**Cause:** Plugin not enabled or installed incorrectly.502503**Solution:**5041. Verify extension is installed: **File > Install Extensions** — GhidraMCP should be listed5052. Enable the plugin: **File > Configure > Configure All Plugins > GhidraMCP** (check the box)5063. **Restart Ghidra** after installation/enabling507508### Server not responding / Connection refused509510**Cause:** Server not started or wrong port.511512**Solution:**5131. Ensure you started the server: **Tools > GhidraMCP > Start MCP Server**5142. Check configured port: **Edit > Tool Options > GhidraMCP HTTP Server**5153. Check if port is in use:516 ```bash517 # Linux/macOS518 lsof -i :8089519 # Windows520 netstat -ano | findstr :8089521 ```5224. Look for errors in Ghidra console: **Window > Console**523524### `pip install` fails with `error: externally-managed-environment`525526**Cause:** PEP 668. Debian-family distros (Debian 12+, Kali, Ubuntu 23.04+)527mark the system Python as externally managed, so global `pip install` is528blocked to protect apt-managed packages.529530**Solution:** Use a virtual environment — never `--break-system-packages`.531The recommended path is [uv](https://docs.astral.sh/uv/), which manages a532project-local `.venv` automatically:533534```bash535curl -LsSf https://astral.sh/uv/install.sh | sh536cd ghidra-mcp537uv run bridge-mcp-ghidra538```539540Or a classic venv:541542```bash543python3 -m venv .venv && source .venv/bin/activate544pip install -e .545bridge-mcp-ghidra546```547548### `python -m debugger` fails with `ModuleNotFoundError` for `pybag` or `comtypes`549550**Cause:** The standalone debugger server uses optional Windows-only Python551dependencies that are not installed by default.552553**Solution:**554```text555uv sync --group debugger556uv run python -m debugger557```558559If you have both a global Python and a project venv, make sure you install560into and run from the same interpreter.561562### 500 Internal Server Errors563564**Cause:** Server-side exception, often due to missing program data.565566**Solution:**5671. Ensure a binary is loaded in CodeBrowser5682. Run auto-analysis first: **Analysis > Auto Analyze**5693. Check Ghidra console (**Window > Console**) for Java exceptions5704. Some operations require fully analyzed binaries571572### 404 Not Found Errors573574**Cause:** Endpoint doesn't exist or wrong URL.575576**Solution:**5771. Verify endpoint exists: `curl http://127.0.0.1:8089/get_version`5782. Check for typos in endpoint name5793. Ensure you're using correct HTTP method (GET vs POST)580581### Python Ghidra scripts fail with "No script provider found"582583**Cause:** In Ghidra 12.1.2, Jython support is no longer enabled by584default. `.py` scripts need the bundled Jython extension; Python 3585scripts should use PyGhidra instead of the Ghidra Script Manager.586587**Solution:**5881. In the Ghidra Front End, open **File > Install Extensions**.5892. Check **Jython**, restart Ghidra, then refresh Script Manager.5903. For new automation, prefer Java Ghidra scripts or PyGhidra.591592### Extension not appearing in Install Extensions593594**Cause:** JAR file in wrong location.595596**Solution:**5971. Manual install location: `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`5982. Or use: **File > Install Extensions > Add** and select the ZIP file5993. Ensure JAR/ZIP was built for your Ghidra version600601### Build fails with "Ghidra dependencies not found"602603**Cause:** Ghidra JARs not installed in local Maven repository.604605**Solution:**606```text607# Windows (recommended)608python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"609```610611## 📊 Production Performance612613- **MCP Tools**: 272 tools fully implemented614- **Speed**: Sub-second response for most operations615- **Efficiency**: 93% reduction in API calls via batch operations616- **Reliability**: Atomic transactions with all-or-nothing semantics617- **AI Workflows**: Proven documentation prompts refined across hundreds of real functions618- **Deployment**: Automated version-aware deployment script619620## 🛠️ API Reference621622<!-- BEGIN GENERATED API REFERENCE (tools/gen_readme_api_reference.py) -->623624251 MCP tools backed by HTTP endpoints, grouped by catalog category. Generated from [tests/endpoints.json](tests/endpoints.json) by `python -m tools.gen_readme_api_reference --write`; the live schema at `/mcp/schema` is authoritative at runtime. Usage patterns: [docs/prompts/TOOL_USAGE_GUIDE.md](docs/prompts/TOOL_USAGE_GUIDE.md).625626### Program & Session Management627628- `analysis_status` - Get auto-analysis status for open programs629- `close_program` - Close an open program by project path or name630- `create_property_map` - Create a user property map to store typed values keyed by address631- `delete_property_map` - Delete a user property map and all values it holds632- `exit_ghidra` - Save and exit Ghidra633- `get_address_spaces` - List all physical and overlay address spaces in the program (overlays include is_overlay flag and overlayed_space name)634- `get_current_program_info` - Get current program info635- `get_language_metadata` - Dump the program's language description: address spaces, registers, default symbols, endianness, pointer size (issue #192)636- `get_program_options` - Read all options in a program option group with types, current values, defaults, and descriptions637- `get_property` - Read the value stored at an address in a property map638- `import_file` - Import a binary file from disk into the current Ghidra project and open it639- `list_open_programs` - List open programs640- `list_option_groups` - List program option groups (e.g641- `list_project_files` - List project files642- `list_properties` - List (address, value) entries stored in a property map, with pagination643- `list_property_maps` - List user-defined property maps — typed per-address key→value stores644- `open_program` - Open program from project645- `reanalyze` - Trigger full auto-analysis on a program646- `remove_program_option` - Remove an option from a program option group647- `remove_property` - Remove the value stored at a single address in a property map648- `save_all_programs` - Save all open programs649- `save_program` - Save current program650- `set_image_base` - Set the base address of the program (rebases all addresses)651- `set_program_option` - Set a typed program option652- `set_property` - Set a value at an address in a property map653- `switch_program` - Switch current program654655### Project Organization656657- `create_folder` - Create a folder in the project658- `delete_file` - Delete a file from the project659- `delete_project` - Delete a Ghidra project660- `list_projects` - List available Ghidra projects661- `move_file` - Move a program file to a different folder in the project, preserving analysis and documentation662- `move_folder` - Move a project folder and everything under it into another folder663- `project_info` - Get detailed project info including running tools and open programs664665### Headless Project & Program Lifecycle666667Available on the standalone headless server (`GhidraMCPHeadlessServer`).668669- `archive_project` - Archive the currently open project to a Ghidra-native .gar file670- `checkin_program` - Check an open program back in to the shared Ghidra Server as a new version671- `close_project` - Close the currently open project672- `create_project` - Create a new Ghidra project673- `export_program` - Export an open or project-resident program to a Ghidra Zip File (.gzf)674- `get_project_info` - Get info about the currently open project675- `import_program` - Import a Ghidra Zip File (.gzf) into the currently open project as a new DomainFile under target_folder (default '/')676- `load_program` - Load a binary file into the headless server for analysis677- `load_program_from_project` - Load program from Ghidra project (headless)678- `open_project` - Open an existing Ghidra project (.gpr file or directory)679- `restore_project` - Restore a Ghidra .gar archive into a fresh on-disk project at `parent_dir/project_name`680- `server_status` - Check headless server connection status681682### Listing & Enumeration683684- `list_bookmarks` - List bookmarks685- `list_calling_conventions` - List available calling conventions686- `list_classes` - List namespace/class names687- `list_data_items` - List defined data688- `list_data_items_by_xrefs` - List data sorted by xref count689- `list_exports` - List exported symbols690- `list_external_locations` - List external locations691- `list_functions` - List functions with addresses692- `list_functions_enhanced` - List functions with metadata693- `list_globals` - List global variables694- `list_imports` - List imported symbols695- `list_methods` - List all function names with pagination696- `list_namespaces` - List all namespaces697- `list_scripts` - List available Ghidra scripts698- `list_segments` - List memory segments699- `list_strings` - List defined strings700701### Context & Lookups702703- `get_current_address` - Get cursor address (GUI only)704- `get_current_function` - Get function at cursor (GUI only)705- `get_current_selection` - Get highlighted address ranges in the CodeBrowser listing (GUI only)706- `get_entry_points` - Get program entry points707- `get_enum_values` - Get enumeration values708- `get_external_location` - Get external location details709- `get_full_call_graph` - Get full call graph710- `get_function_by_address` - Get function at address711- `get_function_call_graph` - Get call graph712- `get_function_callees` - Get functions called713- `get_function_callers` - Get calling functions714- `get_function_count` - Return the number of functions in the loaded program715- `get_function_jump_targets` - Get jump targets716- `get_function_labels` - Get labels in function717- `get_function_variables` - List all variables in a function718- `get_struct_layout` - Get structure layout719- `get_valid_data_types` - Get valid data type names720721### Search722723- `find_similar_functions` - Find similar functions724- `search_byte_patterns` - Search for byte patterns725- `search_data_types` - Search data types726- `search_functions` - Search functions by name727- `search_functions_enhanced` - Advanced function search728- `search_strings` - Search defined strings by a regex/substring pattern729730### Decompilation & Disassembly731732- `decompile_function` - Decompile function733- `disassemble_bytes` - Disassemble byte range734- `disassemble_function` - Disassemble function735- `force_decompile` - Force fresh decompilation736737### Function Tags, Variables & Attributes738739- `add_function_tag` - Attach one or more tags to a function740- `clear_flow_and_repair` - Run Ghidra's GUI 'Clear Flow and Repair' action on a seed range: clears instruction flow reachable from the seed, then repairs function bodies and re-disassembles retained flow (ClearFlowAndRepairCmd with clear_data=false, clear_labels=false, repair=true)741- `create_function_tag` - Create a program-wide function tag definition with an optional comment742- `delete_function_tag` - Delete a program-wide function tag definition743- `get_function_tags` - List all tags assigned to a specific function744- `list_class_members` - List the member functions of a C++ class745- `list_function_tags` - List all program-wide function tag definitions with their use counts746- `remove_function_tag` - Detach one or more tags from a function747- `search_functions_by_tag` - List all functions that have a specified tag attached748- `set_function_no_return` - Set no-return attribute749- `set_function_tag_comment` - Update the comment/description on an existing program-wide function tag750- `set_function_this_type` - Set the decompiler/database type of the implicit 'this' pointer (ECX on x86 __thiscall/__fastcall)751- `set_variable_type` - Set the data type of a function variable (local OR parameter) by name at the decompiler (high-level) layer752- `set_variables` - Set types and names for multiple variables atomically753754### Cross-References755756- `add_memory_reference` - Create a user-defined cross-reference between two memory addresses that the auto-analyzer can't infer (runtime-populated pointer tables, vtables, late-bound function pointers, missed jump/switch tables)757- `get_bulk_xrefs` - Get xrefs for multiple addresses758- `get_function_xrefs` - Get function cross-references759- `get_xrefs_from` - Get references from address760- `get_xrefs_to` - Get references to address761- `remove_reference` - Remove memory cross-reference(s) from one address to another — the inverse of add_memory_reference762763### Data Types & Structures764765- `add_struct_field` - Add struct field766- `analyze_global_completeness` - Score a global variable's documentation completeness on a budgeted 0-100 scale — the data-address analog of analyze_function_completeness767- `apply_data_type` - Apply data type768- `audit_global` - Audit a global variable's documentation state769- `audit_globals_in_function` - Audit every global variable referenced from within a function in one call770- `clone_data_type` - Clone data type771- `create_array_type` - Create array type772- `create_data_type_category` - Create data type category773- `create_enum` - Create enumeration774- `create_function_signature` - Create function signature type775- `create_pointer_type` - Create pointer type776- `create_struct` - Create structure777- `create_typedef` - Create typedef778- `create_union` - Create union779- `delete_data_type` - Delete data type780- `embed_struct_field` - Replace a structure field with an embedded struct type by value (e.g781- `get_type_size` - Get data type size and info782- `import_data_types` - Import data types from GDT783- `list_data_type_categories` - List data type categories784- `list_data_types` - List data types785- `modify_struct_field` - Modify struct field786- `modify_struct_field_type` - Set a structure field's type by name or offset (offset:N)787- `move_data_type_to_category` - Move data type to category788- `recreate_struct` - Replace a structure in one step: optionally remove an existing same-named type, then create with fields JSON (same shape as create_struct)789- `remove_struct_field` - Remove struct field790- `rename_data_type` - Rename a data type (struct, union, enum, typedef) in place, preserving existing applications of it791- `resize_struct` - Grow or shrink an existing structure by total byte size792- `resolve_duplicate_type` - Find duplicate data types by simple name; delete unused /Demangler size-1 stubs when a larger canonical type exists793- `set_function_prototype` - Set function prototype (return type, param types, calling convention)794- `set_global` - Atomically apply name + type + plate-comment + array length to a global variable795- `set_variable_storage` - Set variable storage796- `validate_data_type` - Validate data type syntax797- `validate_function_prototype` - Validate function prototype798799### Renaming & Labels800801- `batch_rename_function_components` - Batch rename function components802- `create_label` - Create label803- `delete_label` - Delete label at address804- `rename_function` - Rename function by name805- `rename_variables` - Batch rename variables806807### Comments & Bookmarks808809- `batch_set_comments` - Set multiple comments810- `clear_function_comments` - Clear all comments for a function811- `delete_bookmark` - Delete bookmark812- `get_comment` - Get listing comments (plate/pre/eol/post/repeatable) at ANY address, including data addresses (works on functions and data globals alike)813- `set_bookmark` - Set bookmark814- `set_comment` - Set a listing comment of a given kind (plate/pre/eol/post/repeatable) at ANY address, including data addresses815816### Analysis817818- `analyze_api_call_chains` - Analyze API call chains819- `analyze_call_graph` - Analyze function call graph patterns820- `analyze_control_flow` - Analyze control flow821- `analyze_data_region` - Analyze data region822- `analyze_dataflow` - Trace value propagation through a function (PCode graph, forward/backward)823- `analyze_for_documentation` - Composite RE documentation analysis (decompile + classify + variables + completeness)824- `analyze_function_complete` - Comprehensive single-call function analysis825- `analyze_function_completeness` - Analyze documentation completeness826- `analyze_struct_field_usage` - Analyze struct field usage827- `apply_data_classification` - Apply data classification828- `batch_apply_documentation` - Apply all documentation to a function in one call829- `can_rename_at_address` - Check if address can be renamed830- `clear_instruction_flow_override` - Clear flow override831- `configure_analyzer` - Configure an analysis plugin832- `create_function` - Create function at address833- `create_memory_block` - Create memory block834- `delete_function` - Delete function at address835- `detect_array_bounds` - Detect array bounds836- `detect_crypto_constants` - Detect crypto constants837- `detect_malware_behaviors` - Detect malware behaviors838- `extract_iocs_with_context` - Extract IOCs with context839- `find_anti_analysis_techniques` - Find anti-analysis techniques840- `find_code_gaps` - Find gaps of undefined bytes between functions in executable memory841- `find_dead_code` - Find dead code842- `find_next_undefined_function` - Find next undefined function843- `get_assembly_context` - Get assembly context844- `get_field_access_context` - Get field access context845- `get_function_pcode` - Dump raw P-code for a function (issue #192)846- `inspect_memory_content` - Inspect memory bytes847- `list_analyzers` - List available analysis plugins848- `read_memory` - Read raw memory849- `run_analysis` - Run auto-analysis on the current program850- `search_instructions` - Search for instructions by mnemonic and/or operand substring851- `suggest_field_names` - Suggest field names852853### Cross-Binary Documentation & Archive854855- `archive_ingest_function` - Ingest a single function's documentation into the cross-version archive (re_kb.functions on bsim Postgres)856- `archive_ingest_program` - Bulk-ingest every function in a program into the cross-version documentation archive857- `batch_string_anchor_report` - Report of source file strings and their FUN_* functions858- `bulk_fuzzy_match` - Bulk cross-binary function matching859- `find_similar_functions_fuzzy` - Cross-binary fuzzy function matching860- `merge_program_documentation` - Bulk merge: copy all RE documentation (function names, signatures, plate comments, instruction comments at EOL/PRE/POST, non-default labels & global symbols) from one program to another at matching addresses861862### Utility & Documentation Transfer863864- `apply_function_documentation` - Apply function documentation865- `check_connection` - Health check endpoint866- `compare_programs_documentation` - Compare documentation across programs867- `convert_number` - Convert number between bases868- `diff_functions` - Diff two functions869- `find_undocumented_by_string` - Find undocumented functions referencing string870- `get_bulk_function_hashes` - Get bulk function hashes871- `get_function_documentation` - Export function documentation872- `get_function_hash` - Get function hash873- `get_function_signature` - Get function feature signature874- `get_metadata` - Get program metadata875- `get_version` - Get plugin version876- `health` - Health check endpoint for headless server877- `mcp_health` - HTTP server health: pool stats, uptime, memory, active request count878- `mcp_schema` - Machine-readable API schema with endpoint metadata879- `tool_goto_address` - Navigate CodeBrowser listing and decompiler to a specific address880- `tool_launch_codebrowser` - Open a file in CodeBrowser, launching a new one if needed881- `tool_running_tools` - List all running Ghidra tool windows882883### Emulation884885- `emulate_function` - Emulate a single function with controlled register/memory inputs886- `emulate_hash_batch` - Brute-force API hash resolution887888### Scripting889890- `run_ghidra_script` - Run script with output capture891- `run_script_inline` - Run inline script code892893### Ghidra Server & Version Control894895- `server_admin_set_permissions` - Set user permissions on a repository896- `server_admin_terminate_all_checkouts` - Terminate all checkouts in a folder recursively897- `server_admin_terminate_checkout` - Terminate all checkouts on a single file898- `server_admin_users` - List all users on the server899- `server_authenticate` - Register server credentials for programmatic authentication900- `server_checkouts` - List all checked-out files in a folder, including server-side checkouts901- `server_connect` - Connect to a Ghidra server902- `server_disconnect` - Disconnect from the Ghidra server903- `server_repositories` - List repositories on the connected server904- `server_repository_create` - Create a new repository on the server905- `server_repository_file` - Get file info from a server repository906- `server_repository_files` - List files in a server repository folder907- `server_version_control_add` - Add a file to version control908- `server_version_control_checkin` - Check in a version-controlled file909- `server_version_control_checkout` - Check out a version-controlled file910- `server_version_control_undo_checkout` - Undo a file checkout911- `server_version_history` - Get version history for a file912913### Debugger (Ghidra TraceRmi — GUI only)914915On Windows hosts where the bridge's WinDbg debugger proxy is active (`GHIDRA_DEBUGGER_URL`), colliding names get a `_2` suffix (e.g. `debugger_status_2`).916917- `debugger_dynamic_to_static` - Translate a runtime dynamic address from the current trace back to a static Ghidra program address918- `debugger_interrupt` - Interrupt (break into) the running target919- `debugger_launch` - Launch an executable through Ghidra's Trace RMI debugger launcher920- `debugger_launch_offers` - List available debugger launch/attach options for the current program921- `debugger_list_breakpoints` - List all breakpoints in the current trace922- `debugger_modules` - List modules (DLLs/EXEs) loaded in the debugged process923- `debugger_read_memory` - Read memory from the debugged process924- `debugger_registers` - Read CPU registers from the current debug trace snapshot925- `debugger_remove_breakpoint` - Remove a breakpoint at an address926- `debugger_resume` - Resume execution of the debugged process927- `debugger_set_breakpoint` - Set a software execution breakpoint at an address in the trace928- `debugger_stack_trace` - Get the call stack backtrace for the current thread929- `debugger_static_to_dynamic` - Translate a static Ghidra program address to a runtime dynamic address in the current trace930- `debugger_status` - Get debugger status: active trace, thread, execution state, module count931- `debugger_step_into` - Single-step into the next instruction (follows calls)932- `debugger_step_out` - Step out of the current function (run to return)933- `debugger_step_over` - Step over the next instruction (does not follow calls)934- `debugger_traces` - List all open debug traces935936### System937938- `prompt_policy` - Temporarily enable, disable, or query scoped automation prompt handling939940### Symbol (uncategorized)941942- `rename_symbol` - Rename a symbol of any kind943944### Bridge Static Tools945946Defined in the Python bridge itself (instance discovery, tool-group management); always available even before a Ghidra connection. The bridge also proxies 22 `debugger_*` WinDbg tools when `GHIDRA_DEBUGGER_URL` points at the standalone debugger server.947948- `check_tools` - Report which tools are currently registered and callable949- `connect_instance` - Connect the bridge to a specific Ghidra instance950- `import_file` - Import a binary from disk into the current project and open it951- `list_instances` - Discover running Ghidra MCP instances (UDS + TCP port scan)952- `list_tool_groups` - List tool groups and their load state953- `load_tool_group` - Register a tool group's dynamic tools with the MCP client954- `search_tools` - Search the full tool catalog by keyword955- `unload_tool_group` - Unregister a tool group's dynamic tools956957<!-- END GENERATED API REFERENCE -->958959See [CHANGELOG.md](CHANGELOG.md) for version history.960961## 🏗️ Architecture962963```964┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐965│ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │966│ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │967│ (Claude, etc.) │ │ ghidra/) │ │ │968└─────────────────┘ └─────────────────┘ └─────────────────┘969 │ │ │970 MCP Protocol HTTP REST Ghidra API971(stdio/streamable-http) (localhost:8089) (Program, Listing)972```973974### Components975976- **python/bridge_mcp_ghidra/** — Python MCP server package (ships as the `ghidra-mcp-bridge` wheel; `bridge-mcp-ghidra` console script) that translates MCP protocol to HTTP calls (225 catalog entries)977- **GhidraMCP.jar** — Ghidra plugin that exposes analysis capabilities via HTTP (175 GUI endpoints)978- **GhidraMCPHeadlessServer** — Standalone headless server — 183 endpoints, no GUI required979- **ghidra_scripts/** — Collection of automation scripts for common tasks980981## 🔧 Development982983### Building from Source984```bash985# Recommended: direct Python-first workflow986python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"987python -m tools.setup build988python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"989990# Version bump (updates all maintained version references atomically)991python -m tools.setup bump-version --new X.Y.Z992```993994The authoritative build system today is Maven. `tools.setup`, the VS Code tasks, and the documented deploy flow all build through `pom.xml` and write artifacts to `target/`. `build.gradle` remains in the repo as a manual fallback for direct Ghidra/Gradle users, but it is not the primary path.995996### Command Reference997998| Command | What it does |999|---------|-------------|1000| `ensure-prereqs` | Install Python deps + Ghidra Maven JARs in one shot. Start here on a new machine. |1001| `preflight` | Validate Python, build tool, Ghidra path, and JAR availability without making changes. Add `--strict` to also check network reachability. |1002| `build` | Build the plugin JAR and extension ZIP via Maven (or Gradle when `TOOLS_SETUP_BACKEND=gradle`). |1003| `deploy` | Copy the built extension into the Ghidra profile and patch `FrontEndTool.xml` for auto-activation. |1004| `start-ghidra` | Launch the configured Ghidra installation. |1005| `clean` | Remove Maven/Gradle build outputs (`target/`, `build/`). |1006| `clean-all` | Remove build outputs plus local cache artifacts (`.m2` Ghidra JARs, etc.). |1007| `install-ghidra-deps` | Install only the Ghidra JARs into `~/.m2`. Useful when the build environment changes. |1008| `install-python-deps` | Install the Python dependency groups via `uv sync`. |1009| `run-tests` | Run the Java offline test suite (no live Ghidra needed). |1010| `verify-version` | Check that version strings are consistent across `pom.xml`, `CHANGELOG.md`, and `README.md`. |1011| `bump-version --new X.Y.Z` | Atomically update all version references. Pass `--tag` to create a git tag. |10121013Common flags accepted by most commands:10141015| Flag | Description |1016|------|-------------|1017| `--ghidra-path PATH` | Ghidra installation directory. Defaults to `GHIDRA_PATH` from `.env`. |1018| `--dry-run` | Print actions without executing them. |1019| `--force` | Reinstall Ghidra JARs even if already present (`install-ghidra-deps`, `ensure-prereqs`). |1020| `--with-debugger` | Force-install debugger Python requirements (Windows only). |1021| `--use-debugger-toggle` | Read `INSTALL_DEBUGGER_DEPS` from `.env` to decide whether to install debugger deps. |1022| `--test TIER` | (`deploy` only) Opt into live deploy regression tiers such as `release` or `debugger-live`. |1023| `--strict` | (`preflight` only) Also check network reachability for Maven Central and PyPI. |10241025Deploy test tiers are opt-in because benchmark tiers can import/reset1026`Benchmark.dll` and `BenchmarkDebug.exe` in the active Ghidra project. Use1027`--test release` before cutting releases, or set1028`GHIDRA_MCP_DEPLOY_TESTS=release` in a local `.env` when you want every deploy1029on your machine to run the live benchmark regression. See1030[Testing and Release Regression](docs/TESTING.md).10311032```text1033# Standard first-time setup and deploy1034python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"1035python -m tools.setup build1036python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"10371038# Preflight check before deploying1039python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"10401041# Version bump and tag1042python -m tools.setup bump-version --new X.Y.Z --tag10431044# Run offline Java tests1045python -m tools.setup run-tests10461047# Show full help1048python -m tools.setup --help1049```10501051### Project Structure1052```1053ghidra-mcp/1054├── pyproject.toml # uv project (ghidra-mcp-bridge wheel + dependency groups)1055├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)1056├── src/main/java/ # Ghidra plugin + headless server (Java)1057│ └── com/xebyte/1058│ ├── GhidraMCPPlugin.java # GUI plugin (196 endpoints)1059│ ├── headless/ # Headless server (183 endpoints)1060│ └── core/ # Shared service layer (12 services)1061├── debugger/ # Optional standalone debugger server (port 8099)1062├── ghidra_scripts/ # Automation scripts for batch workflows1063├── tests/ # Python unit tests + endpoint catalog1064│ ├── unit/ # Catalog consistency, schema, tool function tests1065│ └── endpoints.json # Endpoint specification (225 entries)1066├── docs/ # Documentation1067│ ├── prompts/ # AI workflow prompts (V5 documentation workflows)1068│ ├── releases/ # Version release notes1069│ └── project-management/ # Contributor planning docs (Gradle migration, etc.)1070├── tools/setup/ # Build and deployment CLI (python -m tools.setup)1071├── fun-doc/ # Internal RE curation tool — not part of the MCP plugin1072│ # Priority-queue worker, LLM scoring, web dashboard.1073│ # See fun-doc/README.md for details.1074└── .github/workflows/ # CI/CD pipelines1075```10761077### Library Dependencies10781079Ghidra JARs must be installed into your local Maven repository (`~/.m2/repository`) before compilation.1080This is a one-time setup per machine, and again when your Ghidra version changes.1081`-Deploy` now installs these automatically by default.10821083The tool enforces version consistency between:1084- `pom.xml` (`ghidra.version`)1085- `--ghidra-path` version segment (e.g., `ghidra_12.1.2_PUBLIC`)10861087If these do not match, deployment fails fast with a clear error.10881089### Troubleshooting: Version Mismatch10901091If you see a version mismatch error, align both values:10921. `pom.xml` → `ghidra.version`10932. `--ghidra-path` version segment (`ghidra_X.Y.Z_PUBLIC`)10941095Then rerun:10961097```text1098python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"1099```11001101```text1102# Windows1103python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"1104```11051106**Required Libraries (14 JARs, ~37MB):**11071108| Library | Source Path | Purpose |1109|---------|------------|---------|1110| **Base.jar** | `Features/Base/lib/` | Core Ghidra functionality |1111| **Decompiler.jar** | `Features/Decompiler/lib/` | Decompilation engine |1112| **PDB.jar** | `Features/PDB/lib/` | Microsoft PDB symbol support |1113| **FunctionID.jar** | `Features/FunctionID/lib/` | Function identification |1114| **SoftwareModeling.jar** | `Framework/SoftwareModeling/lib/` | Program model API |1115| **Project.jar** | `Framework/Project/lib/` | Project management |1116| **Docking.jar** | `Framework/Docking/lib/` | UI docking framework |1117| **Generic.jar** | `Framework/Generic/lib/` | Generic utilities |1118| **Utility.jar** | `Framework/Utility/lib/` | Core utilities |1119| **Gui.jar** | `Framework/Gui/lib/` | GUI components |1120| **FileSystem.jar** | `Framework/FileSystem/lib/` | File system support |1121| **Graph.jar** | `Framework/Graph/lib/` | Graph/call graph analysis |1122| **DB.jar** | `Framework/DB/lib/` | Database operations |1123| **Emulation.jar** | `Framework/Emulation/lib/` | P-code emulation |11241125> **Note**: Libraries are NOT included in the repository (see `.gitignore`). You must install them from your Ghidra installation before building.11261127> **Automation entry point**:1128> - `python -m tools.setup` is the supported setup/build/deploy/versioning interface1129> - use `ensure-prereqs`, `build`, `deploy`, `preflight`, `clean-all`, and `bump-version` directly1130> - these commands currently use Maven as the canonical Java build backend11311132### Development Features1133- **Automated Deployment**: Version-aware deployment script1134- **Batch Operations**: Reduces API calls by 93%1135- **Atomic Transactions**: All-or-nothing semantics1136- **Comprehensive Logging**: Debug and trace capabilities11371138## 📚 Documentation11391140### Core Documentation1141- [Documentation Index](docs/README.md) - Complete documentation navigation1142- [Project Structure](docs/PROJECT_STRUCTURE.md) - Project organization guide1143- [Testing and Release Regression](docs/TESTING.md) - Local tests, CI, live Ghidra regression, and release gates1144- [Naming Conventions](docs/NAMING_CONVENTIONS.md) - Code naming standards1145- [Hungarian Notation](docs/HUNGARIAN_NOTATION.md) - Variable naming guide11461147### AI Workflow Prompts1148- [Function Documentation V5](docs/prompts/FUNCTION_DOC_WORKFLOW_V5.md) — Primary workflow: 7-step process with Hungarian notation, type auditing, and verification scoring1149- [Batch Documentation V5](docs/prompts/FUNCTION_DOC_WORKFLOW_V5_BATCH.md) — Parallel subagent dispatch for multi-function processing1150- [Orphaned Code Discovery](docs/prompts/ORPHANED_CODE_DISCOVERY_WORKFLOW.md) — Automated scanner for undiscovered functions1151- [Data Type Investigation](docs/prompts/DATA_TYPE_INVESTIGATION_WORKFLOW.md) — Systematic structure discovery1152- [Cross-Version Matching](docs/prompts/CROSS_VERSION_MATCHING_COMPREHENSIVE.md) — Hash-based function matching1153- [Quick Start Prompt](docs/prompts/QUICK_START_PROMPT.md) — Simplified beginner workflow1154- [All Prompts](docs/prompts/README.md) — Complete prompt index11551156### Release History1157- [Complete Changelog](CHANGELOG.md) - All version release notes1158- [Release Notes](docs/releases/) - Detailed release documentation11591160## 🐳 Headless Server (Docker)11611162GhidraMCP includes a headless server mode for automated analysis without the Ghidra GUI.11631164### Quick Start with Docker11651166```bash1167# Build and run1168docker-compose up -d ghidra-mcp11691170# Test connection1171curl http://localhost:8089/check_connection1172# Connection OK - GhidraMCP Headless Server v7.0.01173```11741175### Headless API Workflow11761177```bash1178# 1. Load a binary1179curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program11801181# 2. Run auto-analysis (identifies functions, strings, data types)1182curl -X POST http://localhost:8089/run_analysis11831184# 3. List discovered functions1185curl "http://localhost:8089/list_functions?limit=20"11861187# 4. Decompile a function1188curl "http://localhost:8089/decompile_function?address=0x401000"11891190# 5. Get metadata1191curl http://localhost:8089/get_metadata1192```11931194### Key Headless Endpoints11951196| Endpoint | Method | Description |1197|----------|--------|-------------|1198| `/load_program` | POST | Load binary file for analysis |1199| `/run_analysis` | POST | Run Ghidra auto-analysis |1200| `/list_functions` | GET | List all discovered functions |1201| `/list_exports` | GET | List exported symbols |1202| `/list_imports` | GET | List imported symbols |1203| `/decompile_function` | GET | Decompile function to C code |1204| `/create_function` | POST | Create function at address |1205| `/get_metadata` | GET | Get program metadata |1206| `/create_project` | POST | Create a Ghidra project |1207| `/list_analyzers` | GET | List available analyzers |1208| `/server/status` | GET | Check Ghidra Server connection |12091210### Configuration12111212Environment variables for Docker:1213- `GHIDRA_MCP_PORT` - Server port (default: 8089)1214- `GHIDRA_MCP_BIND_ADDRESS` - Bind address (default: 0.0.0.0 in Docker)1215- `JAVA_OPTS` - JVM options (default: -Xmx4g -XX:+UseG1GC)12161217## 🤝 Contributing12181219See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.12201221### Quick Start12221. Fork the repository12232. Create a feature branch (`git checkout -b feature/amazing-feature`)12243. Build and test your changes (`mvn clean package assembly:single -DskipTests` or `GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension`)12254. Update documentation as needed12265. Commit your changes (`git commit -m 'Add amazing feature'`)12276. Push to the branch (`git push origin feature/amazing-feature`)12287. Open a Pull Request12291230## 📄 License12311232This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.12331234## 🏆 Production Status12351236| Metric | Value |1237|--------|-------|1238| **Version** | 7.0.0 |1239| **MCP Tools** | 249 fully implemented |1240| **GUI Endpoints** | 196 (GhidraMCPPlugin) |1241| **Headless Endpoints** | 195 (GhidraMCPHeadlessServer) |1242| **Compilation** | ✅ 100% success |1243| **Batch Efficiency** | 93% API call reduction |1244| **AI Workflows** | 7 proven documentation workflows |1245| **Ghidra Scripts** | Automation scripts included |1246| **Documentation** | Comprehensive with AI prompts |12471248See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.124912501251## 🙏 Acknowledgments12521253This project was originally derived from [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP) in August 2025 and has since been substantially rewritten and extended. We acknowledge LaurieWired's original work as the starting point. See [NOTICE](NOTICE) for license attribution.12541255## 👥 Contributors12561257This project has benefited from the work of dedicated contributors:12581259### Core Contributors12601261**[@heeen](https://github.com/heeen)** — Significant contributions including:1262- Fuzzy function matching and structured diff for cross-binary comparison (#13)1263- Script execution improvements and bug fixes (#12)1264- New API endpoints: `save_program`, `exit_ghidra`, `delete_function`, `create_memory_block`, `run_script_inline` (#11)1265- Architectural vision: annotation-driven design, UDS transport, Python bridge optimization proposals12661267**[@huehuehuehueing](https://github.com/huehuehuehueing)** — Significant contributions including:1268- Address-space prefix support — added `<space>:<hex>` syntax (e.g., `mem:1000`, `code:ff00`) to address parsing across the entire endpoint surface, unlocking multi-space targets like embedded firmware (#84, closes #65)1269- Optional `program` parameter + required-param schema fixes — made `program` optional on every endpoint with a sane currentProgram fallback, and fixed several required-vs-optional schema bugs the catalog had inherited (#92)1270- Seeded #44 (data-type / enum tools) — the issue that motivated the v5.0 enum + struct enforcement layer127112721273- **Ghidra Team** - For the incredible reverse engineering platform1274- **Model Context Protocol** - For the standardized AI integration framework1275- **Contributors** - For testing, feedback, and improvements12761277---12781279## 🔗 Related Projects12801281- [re-universe](https://github.com/bethington/re-universe) — Ghidra BSim PostgreSQL platform for large-scale binary similarity analysis. Pairs perfectly with GhidraMCP for AI-driven reverse engineering workflows.1282- [cheat-engine-server-python](https://github.com/bethington/cheat-engine-server-python) — MCP server for dynamic memory analysis and debugging.12831284---12851286**Ready for production deployment with enterprise-grade reliability and comprehensive binary analysis capabilities.**1287
Full transparency — inspect the skill content before installing.