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 and does not expose interface.get.

• Bounded Scans: Address-ordered list results support cooperative cancellation and cursor pagination.

• Atomic Transactions: The bridge executes batch operations. It reverts a transaction after an error.

• Headless Mode: The bridge runs in Ghidra headless scripts without GUI interaction.

Related MCP server: ghidra-mcp-aarch64

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 the target binary with auto-analysis. 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 a saved project file without a new 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

Security Rules

The bridge enforces strict security boundaries:

• Loopback Default: Listeners bind to 127.0.0.1 by default.

• Mandatory Token: A listener on a non-loopback interface requires token.

• Bearer Header: Inbound requests must send Authorization: Bearer <token>.

• Query Token Rejection: The server rejects tokens in URL query strings with HTTP 400.

• Log Privacy: The server never writes secret tokens 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 methods and schemas that the server supports.

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, and other domain tools.

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

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

Requests that use 2026-07-28 must also send MCP metadata and headers. The server supports initialize clients with versions 2025-06-18 and 2025-11-25. See the 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 configuration, workflows, and quality checks.

• 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 you commit changes:

./gradlew --no-daemon clean verify

The verify task checks:

• Architecture boundary rules.

• Generated API contract drift.

• Generated script build and compilation.