SuperghidraMCP - Ghidra Model Context Protocol Server

SuperghidraMCP is the official Model Context Protocol (MCP) server for SuperGhidra, built on pyghidra-mcp. It exposes 56 registered tools (61 defined) directly to AI agents (Claude Code, Antigravity, Cursor, Codex), featuring private session forks, persistent lock-free daemon cache, GPU ARM64 sweeps, Z3 SMT equivalence verification, and MSVC/MFC C++ recovery.

Overview

superghidra-mcp is a command-line Model Context Protocol (MCP) server that brings the full analytical power of Ghidra, a robust software reverse engineering (SRE) suite, into the world of intelligent agents and LLM-based tooling. It bridges Ghidra’s ProgramAPI and FlatProgramAPI to Python using pyghidra and jpype, then exposes that functionality via the Model Context Protocol.

MCP is a unified interface that allows language models, development tools (like VS Code), and autonomous agents to access structured context, invoke tooling, and collaborate intelligently. Think of MCP as the bridge between powerful analysis tools and the LLM ecosystem.

With superghidra-mcp, Ghidra becomes an intelligent backend—ready to respond to context-rich queries, automate deep reverse engineering tasks, and integrate into AI-assisted workflows.

superghidra-mcp now supports two operating modes:

• headless mode for CLI-driven analysis and automation
• --gui mode, which launches Ghidra through superghidra-mcp and shares live program state with the running GUI

Yet another Ghidra MCP?

Yes, the original ghidra-mcp is fantastic. But superghidra-mcp takes a different approach:

• 🐍 Headless-first, GUI-capable – Run entirely via CLI for streamlined automation, or launch Ghidra with --gui when you want live GUI navigation and edits.
• 🔁 Designed for automation – Ideal for integrating with LLMs, CI pipelines, and tooling that needs repeatable behavior.
• ✅ CI/CD friendly – Built with robust unit and integration tests for both client and server sessions.
• 🚀 Quick startup – Asynchronous startup allows the server to start handling requests while binaries are still being analyzed in the background. Supports fast command-line launching with minimal setup.
• 📦 Project-wide analysis – Enables concurrent reverse engineering of all binaries in a Ghidra project
• 🤖 Agent-ready – Built for intelligent agent-driven workflows and large-scale reverse engineering automation.
• 🔍 Semantic code search – Uses vector embeddings (via ChromaDB) to enable fast, fuzzy lookup across decompiled functions, comments, and symbols—perfect for pseudo-C exploration and agent-driven triage.

This project provides a Python-first experience optimized for local development, headless environments, and testable workflows.

Setup Diagrams

How the Pieces Connect

flowchart LR
    subgraph Clients["Clients"]
        Agent["MCP host / agent"]
        Cli["superghidra-mcp-cli"]
        User["Ghidra user"]
    end

    subgraph Process["superghidra-mcp process"]
        Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
        Tools["MCP tools"]
        Context["PyGhidra context"]
    end

    Project["Ghidra project<br/>.gpr / .rep"]
    Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
    Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]

    Agent -->|"HTTP (recommended)"| Transport
    Cli -->|"HTTP only"| Transport
    Transport --> Tools
    Tools --> Context
    Context --> Project
    Context --> Artifacts
    Context -.-> Gui
    User -.-> Gui
    Gui -.-> Project

Choosing a Mode

flowchart TD
    Start["What do you need?"]
    Start --> Headless["Agent or automation"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Http["superghidra-mcp<br/>--transport streamable-http"]
    GuiNeed --> GuiMode["superghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
    Terminal --> HttpServer["Start superghidra-mcp<br/>--transport streamable-http"]
    HttpServer --> CliMode["Run superghidra-mcp-cli commands"]

• Headless MCP: use streamable-http. It keeps Ghidra and its project alive as one long-running server and works with both MCP hosts and the CLI client.
• GUI mode: superghidra-mcp launches Ghidra, opens the project, and exposes extra tools that steer the CodeBrowser in the same JVM.
• CLI client: superghidra-mcp-cli is an HTTP client. Start a streamable-http server first, then issue terminal commands against that running server.
• stdio: retain this only for MCP hosts that cannot connect to an HTTP endpoint.

flowchart TD
    subgraph Clients
        Agent["LLM / MCP host"]
        Cli["superghidra-mcp-cli"]
        Automation["scripts and CI"]
    end

    subgraph Transports
        Stdio["stdio"]
        Http["streamable-http"]
        Sse["sse legacy"]
    end

    subgraph Server["superghidra-mcp server"]
        McpServer["MCPServer tool server"]
        Context["PyGhidra context"]
        Indexing["background analysis and Chroma indexing"]

        subgraph Tools["MCP tools"]
            Analysis["decompile, xrefs, bytes, callgraph"]
            Search["symbols, strings, code"]
            ProjectOps["import, delete, metadata, list binaries"]
            Edits["rename function, rename variable, set type, set prototype, set comment"]
            GuiOnly["GUI only: open program, goto, list open programs, set current program"]
        end
    end

    subgraph GhidraRuntime["Ghidra runtime"]
        PyGhidra["pyghidra"]
        Jpype["JPype shared JVM"]
        Project["Ghidra project"]
        Programs["program databases"]
        CodeBrowser["Ghidra GUI / CodeBrowser"]
    end

    Agent --> Http
    Automation --> Http
    Automation --> Sse
    Cli --> Http

    Stdio --> McpServer
    Http --> McpServer
    Sse --> McpServer

    McpServer --> Context
    Context --> PyGhidra
    PyGhidra --> Jpype
    Jpype --> Project
    Project --> Programs
    Context --> Indexing
    Indexing --> Search

    McpServer --> Tools
    Tools --> Context
    GuiOnly -.-> CodeBrowser
    Context -.-> CodeBrowser

Contents

• SuperghidraMCP - Ghidra Model Context Protocol Server
  • Overview
  • Yet another Ghidra MCP?
  • Setup Diagrams
    • How the Pieces Connect
    • Choosing a Mode
  • Contents
  • Getting started
  • Optimized for Agents
  • CLI Client
    • Installation
    • Quick Start with CLI
  • Project Creation, Management, and Opening Existing Projects
    • Creating New Projects
      • Self-Contained Project Structure
      • Basic Project Creation
      • Custom Project Creation
      • Creating Multiple Related Projects
    • Opening Existing Ghidra Projects
      • Opening by .gpr File
    • GUI Mode
    • Startup Defaults and Large Projects
    • Multiple Agents on One Project
  • Development
    • Setup
    • Testing and Quality
  • API
    • Tools
      • Batch Operations
      • Read / Analysis Tools
      • Project Operations
      • Edit / Mutation Tools
      • GUI Control Tools (--gui only)
  • Usage
    • Mapping Binaries with Docker
    • Streamable HTTP
      • Python
      • Docker
    • Claude Code
    • Codex
    • Standard Input/Output (stdio)
      • Python
      • Docker
    • Using with OpenWeb-UI and MCPO
      • With uvx
      • With Docker
    • Server-sent events (SSE)
      • Python
      • Docker
  • Inspiration
  • Contributing, community, and running from source
    • Contributor workflow

Getting started

Install superghidra-mcp from repository source:

git clone https://github.com/yuatemycat/SuperghidraMCP.git
cd SuperghidraMCP
pip install -e .

Start a persistent Streamable HTTP server:

superghidra-mcp \
  --transport streamable-http \
  --project-path /absolute/path/to/ghidra-projects \
  /absolute/path/to/binary

The server is then available at http://127.0.0.1:8000/mcp. Leave it running and configure your MCP client to use that URL; the Claude Code and Codex examples below show the expected configuration.

To launch and control a live Ghidra GUI from MCP, use --gui with streamable-http:

superghidra-mcp \
  --gui \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --project-path /absolute/path/to/ghidra-projects \
  --project-name my_project

Or, run as a Docker container:

docker run --rm -p 8000:8000 ghcr.io/yuatemycat/superghidra-mcp:latest

Optimized for Agents

superghidra-mcp keeps the MCP surface intentionally narrow so agent clients spend fewer tokens on tool discovery and argument selection.

• Short tool descriptions: MCP tool docstrings are kept compact so MCPServer tool schemas stay small and cheap to send to models.
• Context discipline: tools return focused structured data instead of dumping whole-program context by default. Decompilation, symbol search, and cross-reference results are shaped to support iterative analysis rather than one large response.
• GUI tools only when relevant: GUI-only controls such as open_program_in_gui, list_open_programs, set_current_program, and goto are only exposed when the server is started with --gui.
• CLI is optional: if MCP is not your preferred interface, superghidra-mcp-cli provides a direct command-line client over HTTP with grouped commands for common edit and analysis workflows.

This keeps the default server usable for LLM agents, IDE integrations, and automation without exposing unnecessary tool surface or GUI-only controls in headless sessions.

CLI Client

For a more interactive command-line experience, you can use the separate superghidra-mcp-cli package, which provides a user-friendly interface for interacting with a running superghidra-mcp server.

Installation

Install the CLI client from the repository source:

cd cli
pip install -e .

Or using uv:

cd cli
uv pip install -e .

Quick Start with CLI

1. Start the server (in one terminal):

superghidra-mcp --transport streamable-http /bin/ls

2. Use the CLI (in another terminal):

# List available binaries
superghidra-mcp-cli list binaries

# Decompile a function
superghidra-mcp-cli decompile --binary ls main

# Decompile with callees, referenced strings, and cross-references
superghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs

# Search for symbols (supports regex patterns)
superghidra-mcp-cli search symbols --binary ls printf -l 10

Project Creation, Management, and Opening Existing Projects

Creating New Projects

You can create new projects in several ways, depending on your workflow:

Self-Contained Project Structure

superghidra-mcp creates a self-contained project structure where each project has its own Ghidra project and superghidra-mcp artifacts. This ensures complete isolation and easy project management.

Basic Project Creation

# Create a new project with default settings
superghidra-mcp

# Creates: 
$ tree superghidra_mcp_projects/
superghidra_mcp_projects/
├── my_project.gpr
├── my_project-superghidra-mcp
│   ├── chromadb
│   └── gzfs
└── my_project.rep

Custom Project Creation

# Create project with custom name and location
superghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis

$ tree ~/analysis/ 
/home/vscode/analysis/
└── malware_study
    ├── malware_analysis.gpr
    ├── malware_analysis-superghidra-mcp
    │   ├── chromadb
    │   └── gzfs
    └── malware_analysis.rep

Creating Multiple Related Projects

# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace

# Project for suspicious binaries
superghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis

# Project for packed malware  
superghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis

Opening Existing Ghidra Projects

If you have existing Ghidra projects (.gpr files), you can open them directly with superghidra-mcp:

Opening by .gpr File

# Open existing Ghidra project (project name derived from filename)
superghidra-mcp --project-path ~/existing/ghidra/my_research.gpr

# Result: ~/existing/ghidra/my_research-superghidra-mcp/
# └── chromadb/, gzfs/ (superghidra-mcp additions)

GUI Mode

Use GUI mode when you want MCP actions to operate against the same live program objects that Ghidra is displaying.

• --gui requires --transport streamable-http (or --transport http as an alias)
• --project-path can be a project directory plus --project-name, or an existing .gpr file. Missing projects are created automatically.
• Ghidra is launched by superghidra-mcp, which keeps GUI and MCP transactions in the same JVM
• GUI-only tools are only exposed when running with --gui

Example:

superghidra-mcp \
  --gui \
  --transport streamable-http \
  --project-path /absolute/path/to/my_research.gpr

GUI mode is the right choice when you want to:

• open or switch programs in CodeBrowser
• navigate the listing to a function or address
• rename functions or add comments and immediately see those changes in Ghidra

Startup Defaults and Large Projects

superghidra-mcp does not require --wait-for-analysis by default. The server can start while analysis and MCP-side indexing continue in the background.

This matters for large projects:

• starting a project with many binaries does not need to block server startup
• --wait-for-analysis is available when you want a fully analyzed project before serving requests
• for large existing projects, expect analysis and indexing readiness to vary by binary

Current limitation:

• Ghidra analysis state and MCP indexing state are separate
• a binary can be fully analyzed in Ghidra while search_strings or semantic search_code are still waiting on MCP-side indexing
• this is more noticeable when opening larger existing projects

In practice:

• decompilation, navigation, renaming, and comments can still work for a binary while indexing-heavy search features are catching up
• if startup latency matters more than immediate search readiness, keep the default --no-wait-for-analysis
• if immediate readiness matters more than startup time, use --wait-for-analysis

Multiple Agents on One Project

Ghidra lets only one process open a project for writing. There are two ways for several agents to work on the same project:

1. Share one server (live). Start one --transport streamable-http server and point every agent at its URL. All agents see each other's edits immediately. Prefer this whenever your clients can connect over HTTP.
2. Forks (automatic). When each agent launches its own server (typical for stdio configs), the first server holds the project lock and becomes the primary. Any later server finds the project locked and, instead of failing, clones it into a fork and works there:

flowchart LR
    A["Agent A<br/>(primary)"] --> P["main project<br/>shared.gpr"]
    B["Agent B"] -->|"project locked"| F["fork<br/>shared-superghidra-mcp/forks/&lt;id&gt;"]
    F -->|"journal.jsonl:<br/>renames, types,<br/>prototypes, comments"| M["merge_fork<br/>(run by A)"]
    M --> P

• Every edit made on a fork is appended to a journal as soon as it succeeds, with the value before and after the edit. Work survives even if the fork's server is killed before it saves.
• The fork's agent is told it is on a fork (MCP instructions and the session field of list_project_binaries). The primary's list_project_binaries reports how many fork edits are waiting to be merged.
• The primary merges with merge_fork(fork_id). Each edit is matched by address (and by variable storage for locals and parameters), then:
  • applied if the primary still has the fork's starting value,
  • already_applied if the primary already has the fork's result,
  • conflict if the primary changed the same item to something else. Conflicts are skipped and reported, or forced with on_conflict="overwrite".
• Use dry_run=true to preview. Merging is incremental: run it while the fork is still working, then again later; edits that are already resolved are not replayed.
• Imports made on a fork are queued on the primary. Deletions are never replayed.
• Give each agent a stable --fork-label (for example its name). If that agent's server restarts while its fork still has unmerged edits, it resumes that fork instead of starting a new clone.
• discard_fork deletes a stopped fork. Use --on-project-locked fail to turn forking off and exit with an error instead.

Example: two agents configured with the same stdio command, differing only in label:

{
  "mcpServers": {
    "pyghidra": {
      "command": "superghidra-mcp",
      "args": ["-t", "stdio", "--project-path", "/re/shared.gpr", "--fork-label", "claude"]
    }
  }
}

Then ask the agent on the primary: "list the forks and merge them; tell me about any conflicts."

A fork is a snapshot of the main project's last saved state, and it does not receive later changes from the primary. Conflict detection is what keeps that safe.

Development

This project uses a Makefile to streamline development and testing. ruff is used for linting and formatting, and pre-commit hooks are used to ensure code quality.

Setup

1. Install uv: If you don't have uv installed, you can install it using pip:

   pip install uv
   

   Or, follow the official uv installation guide: https://docs.astral.sh/uv/install/

2. Create a virtual environment and install dependencies:

   make dev-setup
   source ./.venv/bin/activate
   

3. Set Ghidra Environment Variable: Download and install Ghidra, then set the GHIDRA_INSTALL_DIR environment variable to your Ghidra installation directory.

   # For Linux / Mac
   export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
   
   # For Windows PowerShell
   [System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\path\to\ghidra')
   

Testing and Quality

The Makefile provides several targets for testing and code quality:

• make run: Run the MCP server.
• make test: Run the full test suite (unit and integration).
• make test-unit: Run unit tests.
• make test-integration: Run integration tests.
• make test-integration-fast: Run the lightweight integration smoke test used by pre-commit.
• make test-integration-gui: Run GUI integration tests. Requires a working Ghidra install and GUI support.
• make lint: Check code style with ruff.
• make format: Format code with ruff.
• make typecheck: Run lightweight static checks with ruff.
• make check: Run all quality checks.
• make dev: Run the development workflow (format and check).
• make build: Build distribution packages.
• make clean: Clean build artifacts and cache.

Recommended split:

• pre-commit: ruff, pyright, unit tests, and one lightweight integration smoke test
• GitHub Actions: full Linux headless integration coverage, Linux GUI under Xvfb, CLI coverage, and current macOS smoke tests
• scheduled CI: older macOS / Ghidra compatibility coverage
• local/manual: heavier environment-specific GUI debugging and release sanity checks

API

Tools

Enable LLMs to perform actions, make deterministic computations, and interact with external services.

Batch Operations

decompile_function and list_xrefs accept a single target or a list of targets, reducing round-trips when analyzing call chains or multiple symbols at once.

// Decompile three functions in one call, with callees and xrefs attached
{
  "binary_name": "firmware.bin",
  "name_or_address": ["main", "init_hardware", "0x08001234"],
  "include_callees": true,
  "include_xrefs": true
}

// Get cross-references for multiple symbols at once
{
  "binary_name": "firmware.bin",
  "name_or_address": ["malloc", "free", "realloc"]
}

Per-item errors are returned inline (other targets still succeed):

[
  {"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
  {"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]

Read / Analysis Tools

• search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0): Search decompiled pseudo-C using semantic vector search or literal matching.

• list_xrefs(binary_name: str, name_or_address: str | list[str]): List cross-references to function(s), symbol(s), or address(es). Accepts a single target or a list for batch lookup.

• gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120): Generates a MermaidJS call graph for a specified function. Supports both "calling" (functions called by the target) and "called" (functions that call the target) directions with multiple visualization types.

• decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30): Decompile function(s) by name or address. Accepts a single target or a list for batch decompilation. Rich response flags attach callees, strings, and/or xrefs to each result. timeout_sec applies per target and bounds each decompilation attempt independently.

• list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): Lists all exported functions and symbols from a specified binary (regex supported for query).

• list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): Lists all imported functions and symbols for a specified binary (regex supported for query).

• read_bytes(binary_name: str, address: str, size: int = 32): Reads raw bytes from memory at a specified address. Hex addresses may include or omit the 0x prefix.

• search_strings(binary_name: str, query: str, limit: int = 100): Searches strings within a binary.

• search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25): Search for symbols within a binary by name. Supports regex patterns (e.g. ^main$, func.*one) with case-insensitive matching, or plain substring queries. Set functions_only=True to exclude labels, variables, and other non-function symbols.

Project Operations

• import_binary(binary_path: str): Imports a binary from a designated path into the current Ghidra project. If the path is a directory, it will recursively scan and import all supported binary files, preserving the directory structure within the Ghidra project.

• list_project_binaries(): Lists binaries in the current Ghidra project. In GUI mode this includes project binaries that exist on disk even if they are not currently open in CodeBrowser.

• list_project_binary_metadata(binary_name: str): Retrieves detailed metadata for a specific binary, including architecture, compiler, executable format, analysis metrics, and file hashes.

• delete_project_binary(binary_name: str): Deletes a binary (program) from the Ghidra project.

Multi-agent Fork Tools

See Multiple Agents on One Project.

• list_forks(): List this project's forks with their status, whether their server is still running, and pending (unmerged) edit counts, plus this session's role (primary or fork).
• merge_fork(fork_id: str, dry_run: bool = False, on_conflict: str = "skip"): Replay a fork's journaled edits into the main project. Runs only on the primary. on_conflict is skip or overwrite.
• discard_fork(fork_id: str): Delete a fork whose server has stopped, along with its unmerged edits.

Edit / Mutation Tools

• rename_function(binary_name: str, name_or_address: str, new_name: str): Rename a function by name or address. In GUI mode this runs as a live Ghidra transaction and updates the open program.

• rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str): Rename a function parameter or local variable by exact name within a specific function. If the name is missing or ambiguous within that function, the tool returns an error instead of guessing. In GUI mode this runs as a live Ghidra transaction and updates the open program.

• set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str): Set the data type for a function parameter or local variable by exact name within a specific function. If the name is missing or ambiguous within that function, the tool returns an error instead of guessing. type_name is parsed using Ghidra's datatype parser against the program datatype manager.

• set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str): Set a function prototype from a full signature string. The tool always runs the prototype through Ghidra's native signature parser and returns the underlying parser or apply error if the prototype is invalid.

• set_comment(binary_name: str, target: str, comment: str, comment_type: str): Set a function/decompiler comment or listing comment. Listing comment targets can be addresses, symbols, or functions. Supported comment_type values are decompiler, plate, pre, eol, post, and repeatable.

GUI Control Tools (--gui only)

These tools are only available when superghidra-mcp is started with --gui and control what the GUI is showing rather than mutating project data directly:

• list_open_programs(): List programs currently open in the Ghidra GUI.
• open_program_in_gui(binary_name: str, new_window: bool = True): Open a project binary in CodeBrowser. By default this opens a new CodeBrowser window. Set new_window=false to reuse a visible CodeBrowser when possible.
• set_current_program(binary_name: str): Make an open program the active/current program in the primary GUI tool context.
• goto(binary_name: str, target: str, target_type: str): Navigate the Ghidra GUI to an address or function. target_type must be address or function.

Usage

This package is installed directly from repository source (it is not currently published on PyPI):

git clone https://github.com/yuatemycat/SuperghidraMCP.git
cd SuperghidraMCP
pip install -e .

$ superghidra-mcp --help
Usage: superghidra-mcp [OPTIONS] [INPUT_PATHS]...

  PyGhidra Command-Line MCP server

Options:
  -v, --version                       Show version and exit.
  -t, --transport [stdio|streamable-http|sse|http]
                                      Transport protocol. SSE is deprecated;
                                      use streamable-http instead. [default: stdio]
  -p, --port INTEGER                  Port for HTTP-based transports. [default: 8000]
  -o, --host TEXT                     Host for HTTP-based transports. [default: 127.0.0.1]
  --project-path PATH                 Directory for a superghidra-mcp project or an
                                      existing Ghidra .gpr file. [default: superghidra_mcp_projects]
  --project-name TEXT                 Ghidra project name. Ignored for .gpr paths.
                                      [default: my_project]
  --threaded / --no-threaded          Allow threaded analysis. [default: threaded]
  --max-workers INTEGER               Number of analysis workers; 0 means CPU count.
                                      [default: 0]
  --wait-for-analysis / --no-wait-for-analysis
                                      Wait for initial analysis before starting.
                                      [default: no-wait-for-analysis]
  --gui / --no-gui                    Launch Ghidra GUI in-process and serve MCP
                                      against GUI-open programs. Cannot attach to
                                      an already-running external Ghidra process.
                                      [default: no-gui]
  --on-project-locked [fork|fail]     When another session holds the project
                                      lock: fork and journal edits for merging,
                                      or exit. [default: fork]
  --fork-label TEXT                   Name for this server's forks; a restarted
                                      server resumes its own unmerged fork.
  --list-project-binaries             List ingested project binaries and exit.
  --delete-project-binary TEXT        Delete a project binary by name and exit.
  --force-analysis / --no-force-analysis
                                      Force a new binary analysis each run.
                                      [default: no-force-analysis]
  --verbose-analysis / --no-verbose-analysis
                                      Verbose logging for analysis. [default: no-verbose-analysis]
  --no-symbols / --with-symbols       Turn off symbols for analysis. [default: with-symbols]
  --sym-file-path PATH                Single PDB symbol file for one binary.
  -s, --symbols-path PATH             Local symbols directory.
  --gdt PATH                          Path to GDT files. May be specified multiple times.
  --program-options PATH              JSON file with Ghidra program options.
  --gzfs-path PATH                    Location to store GZFs of analyzed binaries.
  -h, --help                          Show this message and exit.

Mapping Binaries with Docker

When using the Docker container, you can map a local directory containing your binaries into the container's workspace. This allows superghidra-mcp to analyze your files.

# Create and populate the new directory
mkdir -p ./binaries
cp /path/to/your/binaries/* ./binaries/

# Run the Docker container with volume mapping
docker run -i --rm \
  -v "$(pwd)/binaries:/binaries" \
  ghcr.io/yuatemycat/superghidra-mcp:latest \
  /binaries/*

Streamable HTTP

Streamable HTTP is the recommended transport. It keeps one Ghidra process and project available to MCP hosts and superghidra-mcp-cli, avoiding the startup cost of a separate process per client. It sends JSON-RPC requests over HTTP; see the spec for details.

By default, the server listens on http://127.0.0.1:8000/mcp for client connections. Use --host / --port or the MCP_HOST / MCP_PORT environment variables to change the bind address. The server must be running for clients to connect to it.

Python

superghidra-mcp -t streamable-http

The Python package defaults to stdio, so always include --transport streamable-http when starting the server.

GUI mode uses this transport:

superghidra-mcp \
  --gui \
  --transport streamable-http \
  --project-path /absolute/path/to/my_project.gpr

Docker

docker run -p 8000:8000 ghcr.io/yuatemycat/superghidra-mcp:latest

Claude Code

After starting the HTTP server, add it to Claude Code:

claude mcp add --transport http superghidra-mcp http://127.0.0.1:8000/mcp

For a project-shared configuration, add this to .mcp.json in the project root:

{
  "mcpServers": {
    "superghidra-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

type: "http" is required: an entry with only url is treated as a stdio server by Claude Code. Use claude mcp list or /mcp to verify the connection.

Codex

After starting the HTTP server, add the following to ~/.codex/config.toml:

[mcp_servers.superghidra-mcp]
url = "http://127.0.0.1:8000/mcp"

Restart Codex after saving the configuration. The server name is arbitrary; superghidra-mcp is the name that will appear in Codex.

Standard Input/Output (stdio)

Use stdio only when an MCP host cannot use an HTTP endpoint. It starts a server that communicates over its parent process's standard input and output streams.

Python

superghidra-mcp --transport stdio

Because the server communicates on standard input and output, it will appear to wait without terminal output; that is expected.

Docker

docker run -i --rm ghcr.io/yuatemycat/superghidra-mcp:latest -t stdio

The Docker image starts the Streamable HTTP server by default, so include -t stdio after the image name and use -i for interactive stdio mode.

Using with OpenWeb-UI and MCPO

Use MCPO only when OpenWeb-UI or another consumer specifically requires an OpenAPI proxy. For normal MCP clients, connect directly to the Streamable HTTP endpoint above.

https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95

With uvx

uvx mcpo -- superghidra-mcp /bin/ls

With Docker

uvx mcpo -- docker run -i --rm ghcr.io/yuatemycat/superghidra-mcp:latest /bin/ls

Server-sent events (SSE)

SSE transport enables server-to-client streaming with Server-Send Events for client-to-server and server-to-client communication. See the spec for more details.

By default, the server listens on http://127.0.0.1:8000/sse for client connections. Use --host / --port or the MCP_HOST / MCP_PORT environment variables to change the bind address. The server must be running for clients to connect to it.

Python

superghidra-mcp -t sse

By default, the Python package will run in stdio mode, so you will have to include -t sse.

Docker

docker run -p 8000:8000 ghcr.io/yuatemycat/superghidra-mcp:latest -t sse

Inspiration

This project implementation and design was inspired by these awesome projects:

• GhidraMCP
• semgrep-mcp
• ghidrecomp
• BinAssistMCP

Contributing, community, and running from source

We believe the future of reverse engineering is agentic, contextual, and scalable.
superghidra-mcp is a step toward that future—making full Ghidra projects accessible to AI agents and automation pipelines.

We’re actively developing the project and welcome feedback, issues, and contributions.

Contributor workflow

If you're adding a new tool or integration, here’s the recommended workflow:

• Label your branch with the prefix feature/ to indicate a new capability.
• Add your tool using the same style and structure as existing tools in pyghidra/tools/.
• Write an integration test that exercises your tool using a StdioClient instance. Place it in tests/integration/.
• Extend concurrent testing by adding a call to your tool in tests/integration/test_concurrent_streamable_client.py.
• Run make test and make format to ensure your changes pass all tests and conform to linting rules.

This ensures consistency across the codebase and helps us maintain robust, scalable tooling for reverse engineering workflows.

Made with ❤️ by the SuperghidraMCP Team