Ghidra Bridge

English | 中文 | 日本語

Ghidra Bridge gives network access to an active Ghidra program. The runtime runs on Java 21 and supports Ghidra 12.1. It exposes two transports: WebSocket JSON-RPC 2.0 and MCP Streamable HTTP 2026-07-28. The runtime JAR has zero third-party dependencies.

Key Features

• Dual Transports: Access Ghidra through WebSocket JSON-RPC 2.0 or MCP Streamable HTTP.
• Unified Catalog: One typed registry defines 53 public dotted methods. WebSocket exposes all 53. MCP exposes 52 of them; interface.get is WebSocket only.
• Bounded Scans: Address-ordered listings support cooperative cancellation and cursor pagination.
• Atomic Transactions: Execute batch operations with automatic rollback on error.
• Headless Mode: Run the bridge in Ghidra headless scripts without GUI interaction.

Build the Scripts

Set GHIDRA_INSTALL_DIR to your Ghidra installation path. Then build the scripts with the Gradle wrapper:

./gradlew buildGhidraScript

The build task creates three files in build/ghidra-script/:

Bridge.java
GhidraMcp.java
ghidra-bridge.jar

Keep these three files in the same directory. The loader scripts locate ghidra-bridge.jar relative to their file path.

Start the Bridge

Run in the Ghidra GUI

1. Open a binary in the Ghidra CodeBrowser tool.
2. Open the Script Manager window.
3. Add build/ghidra-script/ to your script directories.
4. Run Bridge.java for WebSocket or GhidraMcp.java for MCP.
5. Enter configuration arguments in the prompt window.

Run in Ghidra Headless Mode

You can run GhidraMcp.java or Bridge.java as a post-script in headless mode. Create a project directory, then import and analyze the target binary. Do not use project paths with dot-prefixed directory names like .cache.

mkdir -p /path/to/projects
"$GHIDRA_INSTALL_DIR/support/analyzeHeadless" /path/to/projects demo \
  -import /path/to/target_binary \
  -scriptPath "$PWD/build/ghidra-script" \
  -postScript GhidraMcp.java host=127.0.0.1 port=8766 path=/mcp session_id=demo

The post-script serves requests until you stop the process. To open an existing project file without re-analysis, use -process with -noanalysis:

"$GHIDRA_INSTALL_DIR/support/analyzeHeadless" /path/to/projects demo \
  -process target_binary -noanalysis \
  -scriptPath "$PWD/build/ghidra-script" \
  -postScript GhidraMcp.java host=127.0.0.1 port=8766 path=/mcp session_id=demo

Configuration Arguments

Configure the bridge with strict key=value pairs. The launcher rejects unknown arguments, duplicate arguments, and camelCase keys.

# Embedded WebSocket server
host=127.0.0.1 port=8765 path=/ws/agent session_id=demo

# Outbound WebSocket client
ws_url=ws://127.0.0.1:8765/ws/agent session_id=demo token=secret

# MCP HTTP server
host=127.0.0.1 port=8766 path=/mcp session_id=demo token=secret

# Second MCP HTTP server with its own tool names
host=127.0.0.1 port=8767 path=/mcp session_id=other tool_prefix=other

Parameter Reference

Parameter	Default	Description
host	127.0.0.1	Local network interface address to listen on.
port	8765 (WS) / 8766 (MCP)	TCP port number for the HTTP or WebSocket server. WebSocket uses the default only when ws_url is not set.
path	/ws/agent (WS) / /mcp (MCP)	URL path endpoint for request dispatch.
session_id	Program name	Unique identifier string for this active session.
token	(none)	Shared secret token for bearer authentication.
ws_url	(none)	Remote WebSocket URL when operating as an outbound client.
tool_prefix	ghidra	MCP only. First part of every tool name, such as ghidra in ghidra.program. Use a different value for each server that one client connects to.
jar	(auto)	Path to ghidra-bridge.jar if moved away from script file.
exit_deadline_sec	(none)	Outbound only. Halt the JVM if Ghidra does not exit this many seconds after the session ends. A save that runs at that time completes first. Use it only for a headless Ghidra that a host starts.

Security Rules

The bridge enforces strict security boundaries:

• Loopback Default: Listeners bind to 127.0.0.1 by default.
• Mandatory Token: A listener bound to a non-loopback interface requires token.
• Bearer Header: Inbound requests must send Authorization: Bearer <token>.
• Query Tokens Rejected: The server rejects tokens in URL query strings with HTTP 400.
• Log Privacy: Secret tokens are never written to log files or consoles.

API and Transports

The public API has 53 dotted methods, from interface.get to batch.execute.

WebSocket JSON-RPC 2.0

WebSocket sends strict JSON-RPC 2.0 requests with dotted method names:

{"jsonrpc":"2.0","id":"r1","method":"program.get","params":{}}

Call interface.get to discover all supported methods and schemas.

Model Context Protocol (MCP)

MCP exposes the same operations, except interface.get, through 15 tools over Streamable HTTP:

• ghidra.help: Discover domains, list operations, or view schemas.
• 14 Domain Tools: ghidra.program, ghidra.memory, ghidra.function, ghidra.listing, etc.

Call an operation with its operation name in the domain tool and its parameters. For example, the program.get method is the get operation of ghidra.program:

{
  "name": "ghidra.program",
  "arguments": {
    "operation": "get",
    "params": {}
  }
}

Requests using 2026-07-28 must also send MCP metadata and headers; clients using initialize are supported with versions 2025-06-18 and 2025-11-25. See Protocol Specification.

The MCP tool schema is also available at ghidra-bridge://contracts/mcp-tools.

Documentation Index

• Overview: System concepts, concurrency model, and query patterns.
• Architecture: Module boundaries and dependency graph.
• Protocol Specification: JSON-RPC envelopes, MCP endpoints, and error formats.
• Batch and Transactions: Atomic execution and transaction boundaries.
• Development Guide: Environment setup, workflows, and quality gates.
• Method Reference: Full 53-method catalog and schemas.
• AsyncAPI Contract: Formal WebSocket contract.
• MCP Tools Contract: Formal MCP tool definitions.

Verify the Build

Run the full verification suite before committing changes:

./gradlew --no-daemon clean verify

The verify task checks:

• Architecture boundary rules.
• Generated API contract drift.
• Generated script build and compilation.

The MCP test suite in tests/ runs every MCP tool against Ghidra in headless mode.