# lauriewired/ghidramcp architecture

> Architecture diagram of the GitHub repository lauriewired/ghidramcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lauriewired/ghidramcp
- Repository: https://github.com/lauriewired/ghidramcp

## Overview

ghidraMCP exposes Ghidra reverse-engineering operations to MCP clients. The principal flow is client → Python MCP tool server → HTTP backend client → Ghidra extension routes → analysis service → results; the extension targets either the active GUI program or a headless program loaded through PyGhidra. The README also documents headless binary import, analysis, and persistent project saves. The graph reflects documented capabilities and sampled routing; some Python and Java internals were not excerpted, so uncertain links are omitted.

Main entry points: [`extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java) (Backend HTTP routes), [`extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java`](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java) (Ghidra analysis service), [`src/ghidra_mcp/cli.py`](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/cli.py) (CLI and mode selection), [`src/ghidra_mcp/headless.py`](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/headless.py) (Headless session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP interface"]
  node_mcp_tools["MCP tool definitions<br/>[server.py]"]
end

subgraph group_python["Python runtime"]
  node_cli["CLI and mode selection<br/>[cli.py]"]
  node_http_client["Backend HTTP client<br/>[backend.py]"]
  node_headless_session["Headless session<br/>[headless.py]"]
end

subgraph group_extension["Ghidra extension"]
  node_plugin["Ghidra plugin"]
  node_http_backend["Backend HTTP routes"]
  node_request["HTTP request parsing<br/>[Request.java]"]
  node_json["JSON responses<br/>[Json.java]"]
  node_gui_provider["GUI program provider"]
  node_headless_backend["Headless backend launcher"]
  node_headless_provider["Headless program provider"]
  node_provider_contract["Program provider contract"]
end

subgraph group_analysis["Analysis operations"]
  node_analysis_service["Ghidra analysis service"]
  node_result_models["Analysis result models<br/>[Model.java]"]
  node_pagination["Paged results<br/>[Page.java]"]
  node_errors["Structured errors<br/>[McpException.java]"]
end

node_mcp_client(("MCP client"))
node_ghidra[("Ghidra program")]

node_mcp_client -->|"starts server"| node_cli
node_cli -->|"creates tools"| node_mcp_tools
node_mcp_tools -->|"calls endpoints"| node_http_client
node_cli -->|"connects backend"| node_http_client
node_cli -->|"starts headless"| node_headless_session
node_headless_session -->|"starts backend"| node_headless_backend
node_headless_session -->|"sets backend URL"| node_http_client
node_http_client -->|"sends HTTP requests"| node_http_backend
node_plugin -->|"configures provider"| node_gui_provider
node_plugin -->|"starts server"| node_http_backend
node_headless_backend -->|"creates provider"| node_headless_provider
node_http_backend -->|"gets program"| node_provider_contract
node_gui_provider -->|"implements"| node_provider_contract
node_headless_provider -->|"implements"| node_provider_contract
node_http_backend -->|"parses requests"| node_request
node_http_backend -->|"formats responses"| node_json
node_http_backend -->|"dispatches operations"| node_analysis_service
node_analysis_service -->|"returns models"| node_result_models
node_analysis_service -->|"builds pages"| node_pagination
node_analysis_service -->|"raises errors"| node_errors
node_analysis_service -.->|"inspects and modifies"| node_ghidra
node_headless_session -->|"loads and saves binary"| node_ghidra
node_mcp_client -.->|"requests analysis"| node_ghidra

click node_cli "https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/cli.py"
click node_mcp_tools "https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/server.py"
click node_http_client "https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/backend.py"
click node_headless_session "https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/headless.py"
click node_plugin "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/GhidraMCPPlugin.java"
click node_http_backend "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java"
click node_request "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/Request.java"
click node_json "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/Json.java"
click node_gui_provider "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/gui/GuiProgramProvider.java"
click node_headless_backend "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessBackend.java"
click node_headless_provider "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessProgramProvider.java"
click node_analysis_service "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java"
click node_result_models "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/Model.java"
click node_pagination "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/Page.java"
click node_errors "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/McpException.java"
click node_provider_contract "https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/ProgramProvider.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_tools,node_mcp_client toneBlue
class node_cli,node_http_client,node_headless_session,node_ghidra toneAmber
class node_plugin,node_http_backend,node_request,node_json,node_gui_provider,node_headless_backend,node_headless_provider,node_provider_contract toneMint
class node_analysis_service,node_result_models,node_pagination,node_errors toneRose
```

## Components

### MCP interface

- [MCP tool definitions](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/server.py): `src/ghidra_mcp/server.py`

### Python runtime

- [CLI and mode selection](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/cli.py): `src/ghidra_mcp/cli.py`
- [Backend HTTP client](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/backend.py): `src/ghidra_mcp/backend.py`
- [Headless session](https://github.com/lauriewired/ghidramcp/blob/main/src/ghidra_mcp/headless.py): `src/ghidra_mcp/headless.py`

### Ghidra extension

- [Ghidra plugin](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/GhidraMCPPlugin.java): `extension/src/main/java/com/lauriewired/GhidraMCPPlugin.java`
- [Backend HTTP routes](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java): `extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`
- [HTTP request parsing](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/Request.java): `extension/src/main/java/com/lauriewired/ghidramcp/http/Request.java`
- [JSON responses](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/http/Json.java): `extension/src/main/java/com/lauriewired/ghidramcp/http/Json.java`
- [GUI program provider](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/gui/GuiProgramProvider.java): `extension/src/main/java/com/lauriewired/ghidramcp/gui/GuiProgramProvider.java`
- [Headless backend launcher](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessBackend.java): `extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessBackend.java`
- [Headless program provider](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessProgramProvider.java): `extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessProgramProvider.java`
- [Program provider contract](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/ProgramProvider.java): `extension/src/main/java/com/lauriewired/ghidramcp/core/ProgramProvider.java`

### Analysis operations

- [Ghidra analysis service](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java): `extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java`
- [Analysis result models](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/Model.java): `extension/src/main/java/com/lauriewired/ghidramcp/core/Model.java`
- [Paged results](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/Page.java): `extension/src/main/java/com/lauriewired/ghidramcp/core/Page.java`
- [Structured errors](https://github.com/lauriewired/ghidramcp/blob/main/extension/src/main/java/com/lauriewired/ghidramcp/core/McpException.java): `extension/src/main/java/com/lauriewired/ghidramcp/core/McpException.java`

### Other components

- **MCP client**
- **Ghidra program**

## Connections

- MCP client → CLI and mode selection: starts server (evidence: `README.md`)
- CLI and mode selection → MCP tool definitions: creates tools (evidence: `src/ghidra_mcp/cli.py`)
- MCP tool definitions → Backend HTTP client: calls endpoints (evidence: `src/ghidra_mcp/server.py`)
- CLI and mode selection → Backend HTTP client: connects backend (evidence: `src/ghidra_mcp/cli.py`)
- CLI and mode selection → Headless session: starts headless (evidence: `src/ghidra_mcp/cli.py`)
- Headless session → Headless backend launcher: starts backend (evidence: `src/ghidra_mcp/headless.py`)
- Headless session → Backend HTTP client: sets backend URL (evidence: `src/ghidra_mcp/headless.py`)
- Backend HTTP client → Backend HTTP routes: sends HTTP requests (evidence: `src/ghidra_mcp/backend.py`)
- Ghidra plugin → GUI program provider: configures provider (evidence: `extension/src/main/java/com/lauriewired/GhidraMCPPlugin.java`)
- Ghidra plugin → Backend HTTP routes: starts server (evidence: `extension/src/main/java/com/lauriewired/GhidraMCPPlugin.java`)
- Headless backend launcher → Headless program provider: creates provider (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessBackend.java`)
- Backend HTTP routes → Program provider contract: gets program (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`)
- GUI program provider → Program provider contract: implements (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/gui/GuiProgramProvider.java`)
- Headless program provider → Program provider contract: implements (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/headless/HeadlessProgramProvider.java`)
- Backend HTTP routes → HTTP request parsing: parses requests (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`)
- Backend HTTP routes → JSON responses: formats responses (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`)
- Backend HTTP routes → Ghidra analysis service: dispatches operations (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/http/BackendHttpServer.java`)
- Ghidra analysis service → Analysis result models: returns models (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java`)
- Ghidra analysis service → Paged results: builds pages (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java`)
- Ghidra analysis service → Structured errors: raises errors (evidence: `extension/src/main/java/com/lauriewired/ghidramcp/core/GhidraAnalysisService.java`)
- Ghidra analysis service → Ghidra program: inspects and modifies
- Headless session → Ghidra program: loads and saves binary (evidence: `src/ghidra_mcp/headless.py`)
- MCP client → Ghidra program: requests analysis
