pyghidra-mcp

PyGhidra-MCP

pyghidra-mcp is a Model Context Protocol (MCP) server that exposes Ghidra's reverse engineering capabilities to AI agents and LLM-based tools. It bridges Ghidra's ProgramAPI and FlatProgramAPI to Python via pyghidra and jpype.

Key Features:

• Headless-first, GUI-capable: Run via CLI for automation or use --gui to launch a live Ghidra instance that shares state with the MCP server.
• Agent-optimized: Uses compact tool descriptions and structured data to minimize token usage for LLM agents.
• Semantic Search: Integrates ChromaDB for vector-based fuzzy lookup across decompiled code, comments, and symbols.
• Automation-ready: Designed for CI/CD, repeatable workflows, and concurrent analysis of multiple binaries within a Ghidra project.

GUI mode allows MCP actions to operate against the same live program objects currently displayed in the Ghidra CodeBrowser. This is ideal for navigating the listing, renaming functions, or adding comments and seeing the changes reflected immediately in the Ghidra UI.

Requirements and Behavior:

• Requires --gui and --transport streamable-http (or --transport http).
• Ghidra is launched by pyghidra-mcp, keeping both GUI and MCP transactions in the same JVM.
• GUI-only tools are only exposed when running with the --gui flag.

Example:

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

The server is designed to be efficient for LLM agents by:

• Minimizing Tool Surface: MCP tool docstrings are kept compact to keep FastMCP tool schemas small and cheap for models to process.
• Context Discipline: Tools return focused, structured data rather than dumping entire program contexts, supporting iterative analysis.
• Conditional Tool Exposure: GUI-specific tools (like goto or set_current_program) are only exposed when the server is explicitly started with the --gui flag, preventing unnecessary noise in headless agent sessions.

The pyghidra-mcp-cli is a client that connects to the pyghidra-mcp server exclusively via HTTP.

Why HTTP?

• No startup overhead: Avoids spawning a new Java/Ghidra process for every command (which can take 10-60 seconds).
• Lifecycle management: The server stays running, allowing multiple commands to use a single Ghidra instance.
• Resource efficiency: One Ghidra instance serves multiple CLI calls.

Connection Model

1. The Server (pyghidra-mcp) manages the Ghidra lifecycle, projects, and binaries.
2. The CLI (pyghidra-mcp-cli) sends commands to the server via HTTP.
3. GUI Commands: If the server is started with --gui, the CLI can interact with the Ghidra GUI (e.g., open, goto).

PyGhidra-MCP operates in different modes depending on your use case:

1. Headless MCP: Best for local MCP hosts (like Claude Desktop) or automation. Use the stdio transport for local hosts, or streamable-http if multiple clients need to connect to the same long-running Ghidra project.
2. GUI Mode: Use this when you need live Ghidra GUI control. When started with --gui, the server launches Ghidra and exposes additional tools to steer the CodeBrowser (e.g., goto, open_program_in_gui).
3. CLI Client Mode: Use pyghidra-mcp-cli to interact with a running streamable-http server via a terminal. This requires starting the server with --transport streamable-http first.

By default, pyghidra-mcp starts the server without waiting for full analysis (--no-wait-for-analysis). This allows the server to start quickly even for large projects, while analysis and MCP-side indexing continue in the background.

Key considerations:

• Ghidra analysis vs. MCP indexing: These are separate states. A binary might be fully analyzed in Ghidra, but semantic search features (like search_strings or search_code) might still be waiting on MCP-side indexing.
• When to use --wait-for-analysis: Use this flag if you require a fully analyzed project before the server begins serving requests. This increases startup time but ensures immediate readiness for all features.
• Default behavior: Decompilation, navigation, renaming, and comments typically work even while indexing-heavy search features are still catching up.

SSE transport enables server-to-client streaming.

WARNING

SSE is considered a legacy transport protocol. Use streamable-http instead.

By default, the server listens on http://127.0.0.1:8000/sse.

Python:

pyghidra-mcp -t sse

Docker:

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

Streamable HTTP enables streaming responses over JSON RPC via HTTP POST requests. This is the recommended transport protocol.

By default, the server listens on http://127.0.0.1:8000/mcp. You can change the bind address using --host/--port or the MCP_HOST/MCP_PORT environment variables.

Python:

pyghidra-mcp -t streamable-http

GUI Mode (Python): To launch the Ghidra GUI in-process and serve MCP against GUI-open programs:

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

Docker:

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

The stdio transport enables communication through standard input and output streams. This is the default mode for the Python package and is useful for local integrations.

Python:

pyghidra-mcp

Note: The tool may appear to hang without output; this is expected behavior for stdio mode.

Docker:

docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

To develop on the CLI package, use the provided Makefile or manual venv setup to install the package in editable mode.

cd cli
make dev-setup      # or create venv manually
pip install -e .

# Run tests
pytest

# Lint
ruff check .