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
If you find this useful, please ⭐ star the repo — it helps others discover it!
If Ghidra MCP saves you time, consider sponsoring the project. One-time and recurring support both help fund compatibility updates, production hardening, docs, and new tooling.
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 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.
You'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.
v5.0 moves conventions from "things to remember" into the tool layer, where they can actually be enforced.
| Tier | Behavior | Example |
|---|---|---|
| Auto-fix | Applied silently | count field on a uint32 → auto-prefixed dwCount on save |
| Warn | Change goes through, warning returned | processData → "name should be PascalCase with a verb: ProcessData" |
| Reject | Change blocked with explanation | undefined → undefined type change → "no-op rejected, type unchanged" |
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.
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.
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.
Compatibility note: MCP tool names are normalized for GitHub Copilot CLI and CAPI validation. Exposed tool names use lowercase letters, digits, underscores, and hyphens only; nested HTTP paths such as
/debugger/statusare advertised as names likedebugger_status_2when needed to avoid collisions with static bridge tools.
EmulatorHelper; brute-force API hash resolution in millisecondsShared Ghidra Server users: Ghidra 12.1.2 clients require a Ghidra Server at 12.1, 12.0.5, or a newer compatible version. Upgrade the server before using this plugin from a 12.1 client.
Ghidra 12.1.2 ships Jython as an optional extension. Java scripts work by default, but
.pyscripts inghidra_scripts/require installing the Jython extension from File > Install Extensions and restarting Ghidra.
Recommended for all platforms: use
python -m tools.setupdirectly.
ensure-prereqsinstalls runtime Python requirements plus the Ghidra JARs needed in the local Maven repository.deploycopies the build output, installs the user-profile extension, and patches Ghidra user config.
Clone the repository:
git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp
Recommended: run environment preflight first:
python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
Build and deploy to Ghidra:
python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
deploy saves/closes an already-running matching Ghidra instance when
needed, installs the extension, starts Ghidra, waits for MCP health, and runs
schema smoke checks.
Optional strict/manual mode (advanced):
# Skip automatic prerequisite setup
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
Show command help:
python -m tools.setup --help
Optional build-only mode (advanced/troubleshooting):
python -m tools.setup build
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.
# Manual Maven build (requires Ghidra deps already installed in local .m2)
mvn clean package assembly:single -DskipTests
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension
Clone the repository:
git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp
Install system prerequisites (if not already installed):
sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
Debian/Kali/Ubuntu 23.04+ note (PEP 668): these distros mark the system Python as externally managed, so a bare
pip installfails witherror: externally-managed-environment. Don't work around it with--break-system-packages— it can corrupt apt-managed tooling. Instead use uv (recommended — it creates and manages a project-local.venvautomatically, and is what this repo's commands use):curl -LsSf https://astral.sh/uv/install.sh | sh uv run bridge-mcp-ghidra # resolves deps into .venv and starts the bridgeor a classic virtual environment:
python3 -m venv .venv && source .venv/bin/activate pip install -e . bridge-mcp-ghidra
Run environment preflight:
python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
Build and deploy to Ghidra (single command):
python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC
python -m tools.setup build
python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
This will:
~/.m2/repositoryGhidraMCP-.zip with Maven~/.config/ghidra/ghidra__PUBLIC/Extensions/preferences with LastExtensionImportDirectoryOptional: setup only Maven dependencies:
python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
Show command help:
python -m tools.setup --help
Linux paths: The extension is installed to
$HOME/.config/ghidra/ghidra__PUBLIC/Extensions/GhidraMCP/. Ghidra config files are in$HOME/.config/ghidra/ghidra__PUBLIC/.
Install prerequisites:
brew install openjdk@21 maven python ghidra
Clone the repository:
git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp
Install Ghidra JARs into local Maven:
python -m tools.setup install-ghidra-deps \
--ghidra-path /opt/homebrew/opt/ghidra/libexec
Build and deploy:
python -m tools.setup ensure-prereqs \
--ghidra-path /opt/homebrew/opt/ghidra/libexec
python -m tools.setup build
python -m tools.setup deploy \
--ghidra-path /opt/homebrew/opt/ghidra/libexec
The extension is installed to ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.
Note:
--ghidra-versionis required when using the Homebrew path because the path contains no version string.
Start Ghidra and enable the plugin:
/opt/homebrew/opt/ghidra/libexec/ghidraRun
In the main project window: Tools > GhidraMCP > Start MCP Server
Configure Cursor/Claude MCP (~/.cursor/mcp.json):
{
"mcpServers": {
"ghidra": {
"command": "uv",
"args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"]
}
}
}
@Pandoriaantje maintains community AUR packages:
ghidra-mcp-git — tracks mainghidra-mcp — tracks tagged releasesInstall with your AUR helper of choice, e.g.:
yay -S ghidra-mcp # or ghidra-mcp-git
uv run bridge-mcp-ghidra # or: python -m bridge_mcp_ghidra
To add the bridge to Autohand Code from a cloned checkout:
autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra
Add --scope project before ghidra to save the server in the current project's .autohand configuration instead of your user configuration.
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081
MCP client config for the HTTP transport (add to your client's MCP config file):
{
"mcpServers": {
"ghidra-mcp-http": {
"url": "http://127.0.0.1:8081/mcp"
}
}
}
Browser-based clients (e.g. MCP Inspector)
work out of the box: the HTTP transports answer CORS preflight (OPTIONS) requests and expose
the mcp-session-id / mcp-protocol-version headers to scripts. Allowed origins mirror the
Host-header policy — loopback on any port is always permitted, plus the bind host and any
hosts listed in GHIDRA_MCP_ALLOWED_HOSTS.
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081
| Flag | Default | Description |
|---|---|---|
--transport | stdio | stdio (AI tools), streamable-http (web clients), sse (deprecated) |
--mcp-host | 127.0.0.1 | Bind host for HTTP transports |
--mcp-port | — | Port for HTTP transports |
--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. |
--no-lazy | (default) | Load all tool groups immediately on connect. Required for most AI clients. |
--default-groups | listing,function,program | Comma-separated groups loaded on connect when --lazy is set. |
Set GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 to make the bridge refuse any program-scoped
call that omits a program selector, returning a clear error instead of letting the call
ride the server's shared "current program" (the one switch_program and the
active GUI tab move).
export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1
uv run bridge-mcp-ghidra
Without this, a call that leaves program= out runs against whichever program
is current, which is fine for a single-program workflow but a hazard once
several programs are open: the call can read or edit the wrong binary with no
error. The hazard is worse when more than one client shares a server, since
each one moves that current-program global out from under the others.
With strict mode on, every program-scoped call must name its target. This
covers every selector that picks an open program: plain program= and the
cross-program tools' source_program/target_program or program_a/program_b
(declared required, but the server still falls back to the current program when
one arrives empty). A forgotten selector surfaces as a loud error on the first
bad call instead of a silent write to the wrong binary. Tools with no program
selector (open_program and close_program take path/name) are unaffected.
Off by default: with the variable unset the bridge sends calls unchanged.
The bridge exposes a large catalog. To keep the model's tool surface small, run
with --lazy (loads only listing,function,program on connect) and let the
model discover the rest on demand instead of registering everything:
search_tools("rename function") — keyword-search the entire catalog,
including tools whose group isn't loaded. Each result says whether it's
callable now and, if not, the exact load_tool_group(...) call to enable it.list_tool_groups() — list all categories and their load state.load_tool_group("datatype") / unload_tool_group("datatype") — load or
drop a category at runtime.check_tools("rename_symbol,batch_set_comments") — confirm specific tools
are callable right now.search_tools works in both eager and --lazy modes, so agents that honor
tools/list_changed get full discovery without the upfront context cost.
uv sync --group debugger
uv run python -m debugger
The debugger server listens on http://127.0.0.1:8099/ by default and is
required for the debugger_* proxy tools exposed by the MCP bridge.
Debugger server flags:
| Flag | Default | Description |
|---|---|---|
--port | 8099 | HTTP server port |
--host | 127.0.0.1 | Bind address (0.0.0.0 to expose on LAN) |
--exports-dir | — | Path to a dll_exports/ directory for ordinal-to-name resolution |
--log-level | INFO | DEBUG, INFO, WARNING, or ERROR |
Set GHIDRA_DEBUGGER_URL in .env if you change the default port or host so the bridge can find it.
http://127.0.0.1:8089/ by default# Quick health check
curl http://127.0.0.1:8089/check_connection
# Expected: "Connected: GhidraMCP plugin running with program ''"
# Get version info
curl http://127.0.0.1:8089/get_version
If Ghidra MCP saves you engineering or reverse-engineering time, consider sponsoring the project.
GhidraMCP 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.
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.
| Env var | Effect |
|---|---|
GHIDRA_MCP_AUTH_TOKEN | When set, every HTTP request must carry Authorization: Bearer . Timing-safe comparison. /mcp/health, /health, /check_connection are exempt. |
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. |
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. |
Name-quality enforcement is separate from security. By default,
rename_function and global write endpoints reject names that fail
the built-in quality gates, and struct field writes apply the built-in field
prefix convention. Disable the built-in convention layer with Edit > Tool
Options > GhidraMCP HTTP Server > Strict Naming Enforcement. The same Tool
Options checkbox covers rename_symbol (all symbol kinds),
set_global, the apply_data_type prefix/type guard, and struct-field
Hungarian prefix auto-fixes in create_struct, add_struct_field, and
modify_struct_field. The setting is read when the MCP server starts or
restarts. Function/global convention warnings are still returned when
enforcement is disabled.
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1 # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs
java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089
When connecting to a shared Ghidra Server, GhidraMCP can suppress the password dialog automatically. It resolves credentials in this order (first non-empty value wins):
Compatibility note: Ghidra 12.1.2 clients require Ghidra Server 12.1.2, 12.0.5, or a newer compatible server. Older shared servers are not safe targets for a 12.1 client upgrade.
GHIDRA_SERVER_PASSWORD environment variable (or .env file in the Ghidra install directory or ~)~/.ghidra-cred — single-line password file in your home directory/.ghidra-credUsername resolves similarly: GHIDRA_SERVER_USER env var → user.name system property.
If 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.
/run_script_inline or /run_ghidra_script, export GHIDRA_MCP_ALLOW_SCRIPTS=1. This is a deliberate breaking change; the prior default was unsafe.Cause: Plugin not enabled or installed incorrectly.
Solution:
Cause: Server not started or wrong port.
Solution:
# Linux/macOS
lsof -i :8089
# Windows
netstat -ano | findstr :8089
pip install fails with error: externally-managed-environmentCause: PEP 668. Debian-family distros (Debian 12+, Kali, Ubuntu 23.04+)
mark the system Python as externally managed, so global pip install is
blocked to protect apt-managed packages.
Solution: Use a virtual environment — never --break-system-packages.
The recommended path is uv, which manages a
project-local .venv automatically:
curl -LsSf https://astral.sh/uv/install.sh | sh
cd ghidra-mcp
uv run bridge-mcp-ghidra
Or a classic venv:
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra
python -m debugger fails with ModuleNotFoundError for pybag or comtypesCause: The standalone debugger server uses optional Windows-only Python dependencies that are not installed by default.
Solution:
uv sync --group debugger
uv run python -m debugger
If you have both a global Python and a project venv, make sure you install into and run from the same interpreter.
Cause: Server-side exception, often due to missing program data.
Solution:
Cause: Endpoint doesn't exist or wrong URL.
Solution:
curl http://127.0.0.1:8089/get_versionCause: In Ghidra 12.1.2, Jython support is no longer enabled by
default. .py scripts need the bundled Jython extension; Python 3
scripts should use PyGhidra instead of the Ghidra Script Manager.
Solution:
Cause: JAR file in wrong location.
Solution:
~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jarCause: Ghidra JARs not installed in local Maven repository.
Solution:
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
251 MCP tools backed by HTTP endpoints, grouped by catalog category. Generated from 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.
analysis_status - Get auto-analysis status for open programsclose_program - Close an open program by project path or namecreate_property_map - Create a user property map to store typed values keyed by addressdelete_property_map - Delete a user property map and all values it holdsexit_ghidra - Save and exit Ghidraget_address_spaces - List all physical and overlay address spaces in the program (overlays include is_overlay flag and overlayed_space name)get_current_program_info - Get current program infoget_language_metadata - Dump the program's language description: address spaces, registers, default symbols, endianness, pointer size (issue #192)get_program_options - Read all options in a program option group with types, current values, defaults, and descriptionsget_property - Read the value stored at an address in a property mapimport_file - Import a binary file from disk into the current Ghidra project and open itlist_open_programs - List open programslist_option_groups - List program option groups (e.glist_project_files - List project fileslist_properties - List (address, value) entries stored in a property map, with paginationlist_property_maps - List user-defined property maps — typed per-address key→value storesopen_program - Open program from projectreanalyze - Trigger full auto-analysis on a programremove_program_option - Remove an option from a program option groupremove_property - Remove the value stored at a single address in a property mapsave_all_programs - Save all open programssave_program - Save current programset_image_base - Set the base address of the program (rebases all addresses)set_program_option - Set a typed program optionset_property - Set a value at an address in a property mapswitch_program - Switch current programcreate_folder - Create a folder in the projectdelete_file - Delete a file from the projectdelete_project - Delete a Ghidra projectlist_projects - List available Ghidra projectsmove_file - Move a program file to a different folder in the project, preserving analysis and documentationmove_folder - Move a project folder and everything under it into another folderproject_info - Get detailed project info including running tools and open programsAvailable on the standalone headless server (GhidraMCPHeadlessServer).
archive_project - Archive the currently open project to a Ghidra-native .gar filecheckin_program - Check an open program back in to the shared Ghidra Server as a new versionclose_project - Close the currently open projectcreate_project - Create a new Ghidra projectexport_program - Export an open or project-resident program to a Ghidra Zip File (.gzf)get_project_info - Get info about the currently open projectimport_program - Import a Ghidra Zip File (.gzf) into the currently open project as a new DomainFile under target_folder (default '/')load_program - Load a binary file into the headless server for analysisload_program_from_project - Load program from Ghidra project (headless)open_project - Open an existing Ghidra project (.gpr file or directory)restore_project - Restore a Ghidra .gar archive into a fresh on-disk project at parent_dir/project_nameserver_status - Check headless server connection statuslist_bookmarks - List bookmarkslist_calling_conventions - List available calling conventionslist_classes - List namespace/class nameslist_data_items - List defined datalist_data_items_by_xrefs - List data sorted by xref countlist_exports - List exported symbolslist_external_locations - List external locationslist_functions - List functions with addresseslist_functions_enhanced - List functions with metadatalist_globals - List global variableslist_imports - List imported symbolslist_methods - List all function names with paginationlist_namespaces - List all namespaceslist_scripts - List available Ghidra scriptslist_segments - List memory segmentslist_strings - List defined stringsget_current_address - Get cursor address (GUI only)get_current_function - Get function at cursor (GUI only)get_current_selection - Get highlighted address ranges in the CodeBrowser listing (GUI only)get_entry_points - Get program entry pointsget_enum_values - Get enumeration valuesget_external_location - Get external location detailsget_full_call_graph - Get full call graphget_function_by_address - Get function at addressget_function_call_graph - Get call graphget_function_callees - Get functions calledget_function_callers - Get calling functionsget_function_count - Return the number of functions in the loaded programget_function_jump_targets - Get jump targetsget_function_labels - Get labels in functionget_function_variables - List all variables in a functionget_struct_layout - Get structure layoutget_valid_data_types - Get valid data type namesfind_similar_functions - Find similar functionssearch_byte_patterns - Search for byte patternssearch_data_types - Search data typessearch_functions - Search functions by namesearch_functions_enhanced - Advanced function searchsearch_strings - Search defined strings by a regex/substring patterndecompile_function - Decompile functiondisassemble_bytes - Disassemble byte rangedisassemble_function - Disassemble functionforce_decompile - Force fresh decompilationadd_function_tag - Attach one or more tags to a functionclear_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)create_function_tag - Create a program-wide function tag definition with an optional commentdelete_function_tag - Delete a program-wide function tag definitionget_function_tags - List all tags assigned to a specific functionlist_class_members - List the member functions of a C++ classlist_function_tags - List all program-wide function tag definitions with their use countsremove_function_tag - Detach one or more tags from a functionsearch_functions_by_tag - List all functions that have a specified tag attachedset_function_no_return - Set no-return attributeset_function_tag_comment - Update the comment/description on an existing program-wide function tagset_function_this_type - Set the decompiler/database type of the implicit 'this' pointer (ECX on x86 __thiscall/__fastcall)set_variable_type - Set the data type of a function variable (local OR parameter) by name at the decompiler (high-level) layerset_variables - Set types and names for multiple variables atomicallyadd_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)get_bulk_xrefs - Get xrefs for multiple addressesget_function_xrefs - Get function cross-referencesget_xrefs_from - Get references from addressget_xrefs_to - Get references to addressremove_reference - Remove memory cross-reference(s) from one address to another — the inverse of add_memory_referenceadd_struct_field - Add struct fieldanalyze_global_completeness - Score a global variable's documentation completeness on a budgeted 0-100 scale — the data-address analog of analyze_function_completenessapply_data_type - Apply data typeaudit_global - Audit a global variable's documentation stateaudit_globals_in_function - Audit every global variable referenced from within a function in one callclone_data_type - Clone data typecreate_array_type - Create array typecreate_data_type_category - Create data type categorycreate_enum - Create enumerationcreate_function_signature - Create function signature typecreate_pointer_type - Create pointer typecreate_struct - Create structurecreate_typedef - Create typedefcreate_union - Create uniondelete_data_type - Delete data typeembed_struct_field - Replace a structure field with an embedded struct type by value (e.gget_type_size - Get data type size and infoimport_data_types - Import data types from GDTlist_data_type_categories - List data type categorieslist_data_types - List data typesmodify_struct_field - Modify struct fieldmodify_struct_field_type - Set a structure field's type by name or offset (offset:N)move_data_type_to_category - Move data type to categoryrecreate_struct - Replace a structure in one step: optionally remove an existing same-named type, then create with fields JSON (same shape as create_struct)remove_struct_field - Remove struct fieldrename_data_type - Rename a data type (struct, union, enum, typedef) in place, preserving existing applications of itresize_struct - Grow or shrink an existing structure by total byte sizeresolve_duplicate_type - Find duplicate data types by simple name; delete unused /Demangler size-1 stubs when a larger canonical type existsset_function_prototype - Set function prototype (return type, param types, calling convention)set_global - Atomically apply name + type + plate-comment + array length to a global variableset_variable_storage - Set variable storagevalidate_data_type - Validate data type syntaxvalidate_function_prototype - Validate function prototypebatch_rename_function_components - Batch rename function componentscreate_label - Create labeldelete_label - Delete label at addressrename_function - Rename function by namerename_variables - Batch rename variablesbatch_set_comments - Set multiple commentsclear_function_comments - Clear all comments for a functiondelete_bookmark - Delete bookmarkget_comment - Get listing comments (plate/pre/eol/post/repeatable) at ANY address, including data addresses (works on functions and data globals alike)set_bookmark - Set bookmarkset_comment - Set a listing comment of a given kind (plate/pre/eol/post/repeatable) at ANY address, including data addressesanalyze_api_call_chains - Analyze API call chainsanalyze_call_graph - Analyze function call graph patternsanalyze_control_flow - Analyze control flowanalyze_data_region - Analyze data regionanalyze_dataflow - Trace value propagation through a function (PCode graph, forward/backward)analyze_for_documentation - Composite RE documentation analysis (decompile + classify + variables + completeness)analyze_function_complete - Comprehensive single-call function analysisanalyze_function_completeness - Analyze documentation completenessanalyze_struct_field_usage - Analyze struct field usageapply_data_classification - Apply data classificationbatch_apply_documentation - Apply all documentation to a function in one callcan_rename_at_address - Check if address can be renamedclear_instruction_flow_override - Clear flow overrideconfigure_analyzer - Configure an analysis plugincreate_function - Create function at addresscreate_memory_block - Create memory blockdelete_function - Delete function at addressdetect_array_bounds - Detect array boundsdetect_crypto_constants - Detect crypto constantsdetect_malware_behaviors - Detect malware behaviorsextract_iocs_with_context - Extract IOCs with contextfind_anti_analysis_techniques - Find anti-analysis techniquesfind_code_gaps - Find gaps of undefined bytes between functions in executable memoryfind_dead_code - Find dead codefind_next_undefined_function - Find next undefined functionget_assembly_context - Get assembly contextget_field_access_context - Get field access contextget_function_pcode - Dump raw P-code for a function (issue #192)inspect_memory_content - Inspect memory byteslist_analyzers - List available analysis pluginsread_memory - Read raw memoryrun_analysis - Run auto-analysis on the current programsearch_instructions - Search for instructions by mnemonic and/or operand substringsuggest_field_names - Suggest field namesarchive_ingest_function - Ingest a single function's documentation into the cross-version archive (re_kb.functions on bsim Postgres)archive_ingest_program - Bulk-ingest every function in a program into the cross-version documentation archivebatch_string_anchor_report - Report of source file strings and their FUN_* functionsbulk_fuzzy_match - Bulk cross-binary function matchingfind_similar_functions_fuzzy - Cross-binary fuzzy function matchingmerge_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 addressesapply_function_documentation - Apply function documentationcheck_connection - Health check endpointcompare_programs_documentation - Compare documentation across programsconvert_number - Convert number between basesdiff_functions - Diff two functionsfind_undocumented_by_string - Find undocumented functions referencing stringget_bulk_function_hashes - Get bulk function hashesget_function_documentation - Export function documentationget_function_hash - Get function hashget_function_signature - Get function feature signatureget_metadata - Get program metadataget_version - Get plugin versionhealth - Health check endpoint for headless servermcp_health - HTTP server health: pool stats, uptime, memory, active request countmcp_schema - Machine-readable API schema with endpoint metadatatool_goto_address - Navigate CodeBrowser listing and decompiler to a specific addresstool_launch_codebrowser - Open a file in CodeBrowser, launching a new one if neededtool_running_tools - List all running Ghidra tool windowsemulate_function - Emulate a single function with controlled register/memory inputsemulate_hash_batch - Brute-force API hash resolutionrun_ghidra_script - Run script with output capturerun_script_inline - Run inline script codeserver_admin_set_permissions - Set user permissions on a repositoryserver_admin_terminate_all_checkouts - Terminate all checkouts in a folder recursivelyserver_admin_terminate_checkout - Terminate all checkouts on a single fileserver_admin_users - List all users on the serverserver_authenticate - Register server credentials for programmatic authenticationserver_checkouts - List all checked-out files in a folder, including server-side checkoutsserver_connect - Connect to a Ghidra serverserver_disconnect - Disconnect from the Ghidra serverserver_repositories - List repositories on the connected serverserver_repository_create - Create a new repository on the serverserver_repository_file - Get file info from a server repositoryserver_repository_files - List files in a server repository folderserver_version_control_add - Add a file to version controlserver_version_control_checkin - Check in a version-controlled fileserver_version_control_checkout - Check out a version-controlled fileserver_version_control_undo_checkout - Undo a file checkoutserver_version_history - Get version history for a fileOn 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).
debugger_dynamic_to_static - Translate a runtime dynamic address from the current trace back to a static Ghidra program addressdebugger_interrupt - Interrupt (break into) the running targetdebugger_launch - Launch an executable through Ghidra's Trace RMI debugger launcherdebugger_launch_offers - List available debugger launch/attach options for the current programdebugger_list_breakpoints - List all breakpoints in the current tracedebugger_modules - List modules (DLLs/EXEs) loaded in the debugged processdebugger_read_memory - Read memory from the debugged processdebugger_registers - Read CPU registers from the current debug trace snapshotdebugger_remove_breakpoint - Remove a breakpoint at an addressdebugger_resume - Resume execution of the debugged processdebugger_set_breakpoint - Set a software execution breakpoint at an address in the tracedebugger_stack_trace - Get the call stack backtrace for the current threaddebugger_static_to_dynamic - Translate a static Ghidra program address to a runtime dynamic address in the current tracedebugger_status - Get debugger status: active trace, thread, execution state, module countdebugger_step_into - Single-step into the next instruction (follows calls)debugger_step_out - Step out of the current function (run to return)debugger_step_over - Step over the next instruction (does not follow calls)debugger_traces - List all open debug tracesprompt_policy - Temporarily enable, disable, or query scoped automation prompt handlingrename_symbol - Rename a symbol of any kindDefined 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.
check_tools - Report which tools are currently registered and callableconnect_instance - Connect the bridge to a specific Ghidra instanceimport_file - Import a binary from disk into the current project and open itlist_instances - Discover running Ghidra MCP instances (UDS + TCP port scan)list_tool_groups - List tool groups and their load stateload_tool_group - Register a tool group's dynamic tools with the MCP clientsearch_tools - Search the full tool catalog by keywordunload_tool_group - Unregister a tool group's dynamic toolsSee CHANGELOG.md for version history.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │
│ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │
│ (Claude, etc.) │ │ ghidra/) │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
MCP Protocol HTTP REST Ghidra API
(stdio/streamable-http) (localhost:8089) (Program, Listing)
ghidra-mcp-bridge wheel; bridge-mcp-ghidra console script) that translates MCP protocol to HTTP calls (225 catalog entries)# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z
The 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.
| Command | What it does |
|---|---|
ensure-prereqs | Install Python deps + Ghidra Maven JARs in one shot. Start here on a new machine. |
preflight | Validate Python, build tool, Ghidra path, and JAR availability without making changes. Add --strict to also check network reachability. |
build | Build the plugin JAR and extension ZIP via Maven (or Gradle when TOOLS_SETUP_BACKEND=gradle). |
deploy | Copy the built extension into the Ghidra profile and patch FrontEndTool.xml for auto-activation. |
start-ghidra | Launch the configured Ghidra installation. |
clean | Remove Maven/Gradle build outputs (target/, build/). |
clean-all | Remove build outputs plus local cache artifacts (.m2 Ghidra JARs, etc.). |
install-ghidra-deps | Install only the Ghidra JARs into ~/.m2. Useful when the build environment changes. |
install-python-deps | Install the Python dependency groups via uv sync. |
run-tests | Run the Java offline test suite (no live Ghidra needed). |
verify-version | Check that version strings are consistent across pom.xml, CHANGELOG.md, and README.md. |
bump-version --new X.Y.Z | Atomically update all version references. Pass --tag to create a git tag. |
Common flags accepted by most commands:
| Flag | Description |
|---|---|
--ghidra-path PATH | Ghidra installation directory. Defaults to GHIDRA_PATH from .env. |
--dry-run | Print actions without executing them. |
--force | Reinstall Ghidra JARs even if already present (install-ghidra-deps, ensure-prereqs). |
--with-debugger | Force-install debugger Python requirements (Windows only). |
--use-debugger-toggle | Read INSTALL_DEBUGGER_DEPS from .env to decide whether to install debugger deps. |
--test TIER | (deploy only) Opt into live deploy regression tiers such as release or debugger-live. |
--strict | (preflight only) Also check network reachability for Maven Central and PyPI. |
Deploy test tiers are opt-in because benchmark tiers can import/reset
Benchmark.dll and BenchmarkDebug.exe in the active Ghidra project. Use
--test release before cutting releases, or set
GHIDRA_MCP_DEPLOY_TESTS=release in a local .env when you want every deploy
on your machine to run the live benchmark regression. See
Testing and Release Regression.
# Standard first-time setup and deploy
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
# Preflight check before deploying
python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
# Version bump and tag
python -m tools.setup bump-version --new X.Y.Z --tag
# Run offline Java tests
python -m tools.setup run-tests
# Show full help
python -m tools.setup --help
ghidra-mcp/
├── pyproject.toml # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/ # Ghidra plugin + headless server (Java)
│ └── com/xebyte/
│ ├── GhidraMCPPlugin.java # GUI plugin (196 endpoints)
│ ├── headless/ # Headless server (183 endpoints)
│ └── core/ # Shared service layer (12 services)
├── debugger/ # Optional standalone debugger server (port 8099)
├── ghidra_scripts/ # Automation scripts for batch workflows
├── tests/ # Python unit tests + endpoint catalog
│ ├── unit/ # Catalog consistency, schema, tool function tests
│ └── endpoints.json # Endpoint specification (225 entries)
├── docs/ # Documentation
│ ├── prompts/ # AI workflow prompts (V5 documentation workflows)
│ ├── releases/ # Version release notes
│ └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/ # Build and deployment CLI (python -m tools.setup)
├── fun-doc/ # Internal RE curation tool — not part of the MCP plugin
│ # Priority-queue worker, LLM scoring, web dashboard.
│ # See fun-doc/README.md for details.
└── .github/workflows/ # CI/CD pipelines
Ghidra JARs must be installed into your local Maven repository (~/.m2/repository) before compilation.
This is a one-time setup per machine, and again when your Ghidra version changes.
-Deploy now installs these automatically by default.
The tool enforces version consistency between:
pom.xml (ghidra.version)--ghidra-path version segment (e.g., ghidra_12.1.2_PUBLIC)If these do not match, deployment fails fast with a clear error.
If you see a version mismatch error, align both values:
pom.xml → ghidra.version--ghidra-path version segment (ghidra_X.Y.Z_PUBLIC)Then rerun:
python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"
Required Libraries (14 JARs, ~37MB):
| Library | Source Path | Purpose |
|---|---|---|
| Base.jar | Features/Base/lib/ | Core Ghidra functionality |
| Decompiler.jar | Features/Decompiler/lib/ | Decompilation engine |
| PDB.jar | Features/PDB/lib/ | Microsoft PDB symbol support |
| FunctionID.jar | Features/FunctionID/lib/ | Function identification |
| SoftwareModeling.jar | Framework/SoftwareModeling/lib/ | Program model API |
| Project.jar | Framework/Project/lib/ | Project management |
| Docking.jar | Framework/Docking/lib/ | UI docking framework |
| Generic.jar | Framework/Generic/lib/ | Generic utilities |
| Utility.jar | Framework/Utility/lib/ | Core utilities |
| Gui.jar | Framework/Gui/lib/ | GUI components |
| FileSystem.jar | Framework/FileSystem/lib/ | File system support |
| Graph.jar | Framework/Graph/lib/ | Graph/call graph analysis |
| DB.jar | Framework/DB/lib/ | Database operations |
| Emulation.jar | Framework/Emulation/lib/ | P-code emulation |
Note: Libraries are NOT included in the repository (see
.gitignore). You must install them from your Ghidra installation before building.
Automation entry point:
python -m tools.setupis the supported setup/build/deploy/versioning interface- use
ensure-prereqs,build,deploy,preflight,clean-all, andbump-versiondirectly- these commands currently use Maven as the canonical Java build backend
GhidraMCP includes a headless server mode for automated analysis without the Ghidra GUI.
# Build and run
docker-compose up -d ghidra-mcp
# Test connection
curl http://localhost:8089/check_connection
# Connection OK - GhidraMCP Headless Server v7.0.0
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program
# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis
# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"
# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"
# 5. Get metadata
curl http://localhost:8089/get_metadata
| Endpoint | Method | Description |
|---|---|---|
/load_program | POST | Load binary file for analysis |
/run_analysis | POST | Run Ghidra auto-analysis |
/list_functions | GET | List all discovered functions |
/list_exports | GET | List exported symbols |
/list_imports | GET | List imported symbols |
/decompile_function | GET | Decompile function to C code |
/create_function | POST | Create function at address |
/get_metadata | GET | Get program metadata |
/create_project | POST | Create a Ghidra project |
/list_analyzers | GET | List available analyzers |
/server/status | GET | Check Ghidra Server connection |
Environment variables for Docker:
GHIDRA_MCP_PORT - Server port (default: 8089)GHIDRA_MCP_BIND_ADDRESS - Bind address (default: 0.0.0.0 in Docker)JAVA_OPTS - JVM options (default: -Xmx4g -XX:+UseG1GC)See CONTRIBUTING.md for detailed contribution guidelines.
git checkout -b feature/amazing-feature)mvn clean package assembly:single -DskipTests or GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
| Metric | Value |
|---|---|
| Version | 7.0.0 |
| MCP Tools | 249 fully implemented |
| GUI Endpoints | 196 (GhidraMCPPlugin) |
| Headless Endpoints | 195 (GhidraMCPHeadlessServer) |
| Compilation | ✅ 100% success |
| Batch Efficiency | 93% API call reduction |
| AI Workflows | 7 proven documentation workflows |
| Ghidra Scripts | Automation scripts included |
| Documentation | Comprehensive with AI prompts |
See CHANGELOG.md for version history and release notes.
This project was originally derived from 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 for license attribution.
This project has benefited from the work of dedicated contributors:
@heeen — Significant contributions including:
save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)@huehuehuehueing — Significant contributions including:
Address-space prefix support — added : 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)
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)
Seeded #44 (data-type / enum tools) — the issue that motivated the v5.0 enum + struct enforcement layer
Ghidra Team - For the incredible reverse engineering platform
Model Context Protocol - For the standardized AI integration framework
Contributors - For testing, feedback, and improvements
Ready for production deployment with enterprise-grade reliability and comprehensive binary analysis capabilities.
Install via CLI
npx mdskills install bethington/ghidra-mcpGhidra MCP Server is a free, open-source AI agent skill. 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
Install Ghidra MCP Server with a single command:
npx mdskills install bethington/ghidra-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
Ghidra MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.