ghidra-mcp-skill

# Ghidra MCP Skill <p align="center"> A lightweight skill and helper CLI for driving <a href="https://github.com/bethington/ghidra-mcp">bethington/ghidra-mcp</a> from local AI agents, headless Docker workflows, and day-to-day reverse engineering sessions. </p> <p align="center"> <a href="https://github.com/bethington/ghidra-mcp"><img alt="Upstream ghidra-mcp" src="https://img.shields.io/badge/Upstream-bethington%2Fghidra--mcp-181717?logo=github"></a> <img alt="Ghidra 12.0.3" src="https://img.shields.io/badge/Ghidra-12.0.3-2f855a"> <img alt="Docker ready" src="https://img.shields.io/badge/Docker-headless%20ready-2496ED?logo=docker&logoColor=white"> <img alt="Python 3" src="https://img.shields.io/badge/Python-3.x-3776AB?logo=python&logoColor=white"> <img alt="Any AI" src="https://img.shields.io/badge/AI-any%20agent-4A5568"> </p> > This repository is not a replacement for the upstream GhidraMCP project. > It is a thin, practical layer on top of it: > > - `SKILL.md` gives an AI a clear workflow for working against GhidraMCP. > - `scripts/ghidra_mcp.py` gives that AI a small helper CLI for health checks, container copies, program loading, analysis, and raw endpoint calls. ## Why this repo exists This repo packages the boring but necessary glue around GhidraMCP so an AI can work against it with less prompting and less manual setup. | Fast checks | Headless aware | Raw endpoint access | AI agnostic | | --- | --- | --- | --- | | Verify the server in one command | Handles Docker copy/load flow cleanly | Call any REST endpoint without rewriting `curl` | Works with any AI that can follow instructions or run shell commands | ## What is inside | File | Purpose | | --- | --- | | `SKILL.md` | The operating instructions an AI follows when using GhidraMCP | | `scripts/ghidra_mcp.py` | Helper CLI for connectivity checks, Docker copy, verify flow, and raw API access | | `references/endpoints.json` | Versioned parity catalog for the documented MCP surface | ## Documented surface This skill tracks the current upstream documentation surface as three separate numbers: | Surface | Count | Meaning | | --- | --- | --- | | Total catalog | `193` | Published endpoint catalog across both runtime modes | | GUI | `175` | Endpoints documented for `GhidraMCPPlugin` | | Headless | `183` | Endpoints documented for `GhidraMCPHeadlessServer` | Validated against the `ghidra-mcp` `v5.1.0` documented catalog carried in `references/endpoints.json`. Use the live schema to verify the active runtime mode. Do not infer headless readiness from release notes alone. ## Prerequisites Before this skill is useful, you need the upstream GhidraMCP project installed and running: - [bethington/ghidra-mcp](https://github.com/bethington/ghidra-mcp) - Ghidra 12.0.3 or a compatible version - Docker Desktop or Docker Engine - Python 3 This skill assumes the common local defaults below: | Setting | Default | | --- | --- | | GhidraMCP URL | `http://127.0.0.1:8089` | | Docker container name | `ghidra-mcp` | | Writable container path | `/data` | ## 1. Install GhidraMCP in Ghidra Start with the upstream repository: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp ``` ### Windows Use the upstream PowerShell deploy script: ```powershell .\ghidra-mcp-setup.ps1 -Deploy -GhidraPath "C:\ghidra_12.0.3_PUBLIC" ``` ### Linux Use the upstream shell deploy script: ```bash ./ghidra-mcp-setup.sh --deploy --ghidra-path ~/ghidra_12.0.3_PUBLIC ``` ### In Ghidra 1. Start Ghidra and open a `CodeBrowser` window. 2. Enable the plugin in `File > Configure > Configure All Plugins > GhidraMCP`. 3. Start the server from `Tools > GhidraMCP > Start MCP Server`. 4. Verify the plugin is reachable: ```bash curl http://127.0.0.1:8089/check_connection ``` ## 2. Install the Docker container from the upstream repo The headless Docker server is built from the upstream repository's `docker/` directory. This repo does not publish its own image. ### Fast path: Docker Compose ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp/docker docker compose up -d curl http://localhost:8089/check_connection ``` That Compose file builds the upstream `docker/Dockerfile`, publishes port `8089`, and creates two persistent volumes: - `ghidra-data` mounted at `/data` - `ghidra-projects` mounted at `/projects` ### Direct image build If you want to build the container explicitly: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp docker build -t ghidra-mcp-headless:latest -f docker/Dockerfile . docker run -d \ --name ghidra-mcp \ -p 8089:8089 \ -v ghidra-data:/data \ -v ghidra-projects:/projects \ ghidra-mcp-headless:latest curl http://localhost:8089/check_connection ``` ### Load one or more binaries into the headless server If your binary is only on the host, copy it into the running container first. The headless flow is sequential. There is no special bulk-upload endpoint. For more than one executable, repeat the same copy and `/load_program` flow for each file and qualify follow-up calls with `program=<basename>` when more than one program may be loaded. ```bash docker cp /absolute/path/to/program.exe ghidra-mcp:/data/program.exe curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program curl -X POST "http://localhost:8089/run_analysis?program=program.exe" curl "http://localhost:8089/list_functions?program=program.exe&limit=20" curl "http://localhost:8089/decompile_function?program=program.exe&address=0x401000" curl "http://localhost:8089/get_metadata?program=program.exe" ``` ## 3. Use this repo with any AI If your AI supports local instruction files or "skills", point it at `SKILL.md`. If your AI can only run shell commands, it can still use the helper script directly: ```bash python3 scripts/ghidra_mcp.py check ``` This makes the repo usable with Codex, Claude, Cursor, Roo, custom agents, or any other AI that can run local commands and read project instructions. ## Helper CLI The helper script wraps the most common local workflow: ```bash python3 scripts/ghidra_mcp.py check python3 scripts/ghidra_mcp.py parity python3 scripts/ghidra_mcp.py copy /absolute/path/to/program.exe python3 scripts/ghidra_mcp.py verify /absolute/path/to/program.exe --analyze python3 scripts/ghidra_mcp.py verify-many /absolute/path/to/eqgame.exe /absolute/path/to/eqmain.dll --analyze python3 scripts/ghidra_mcp.py call POST /load_program --form file=/data/program.exe python3 scripts/ghidra_mcp.py call POST /run_analysis --query program=program.exe python3 scripts/ghidra_mcp.py call GET /list_functions --query program=program.exe --query limit=20 python3 scripts/ghidra_mcp.py call GET /decompile_function --query program=program.exe --query address=0x401000 python3 scripts/ghidra_mcp.py call GET /list_exports python3 scripts/ghidra_mcp.py call GET /get_metadata --query program=program.exe ``` Use `verify-many` when you want the supported headless sequence for multiple binaries without manually retyping `docker cp`, `/load_program`, `/run_analysis`, `/list_functions`, `/decompile_function`, and `/get_metadata` for each program. The parity check compares live `/mcp/schema` output to the versioned reference catalog in this repo and verifies the expected mode-specific count: ```bash python3 scripts/ghidra_mcp.py parity --mode headless ``` Override the defaults when needed: ```bash python3 scripts/ghidra_mcp.py \ --base-url http://127.0.0.1:8089 \ --container ghidra-mcp \ --container-dir /data \ check ``` ## Typical workflow 1. Install the upstream plugin into Ghidra. 2. Start either the GUI server from Ghidra or the headless Docker container from the upstream repo. 3. Point your AI at `SKILL.md`. 4. Let the AI use `scripts/ghidra_mcp.py` for health checks, binary copies, verification, and raw endpoint access. ## References - Upstream project: [bethington/ghidra-mcp](https://github.com/bethington/ghidra-mcp) - Upstream main README: [README.md](https://github.com/bethington/ghidra-mcp/blob/main/README.md) - Upstream Docker docs: [docker/README.md](https://github.com/bethington/ghidra-mcp/blob/main/docker/README.md) - Upstream Compose file: [docker/docker-compose.yml](https://github.com/bethington/ghidra-mcp/blob/main/docker/docker-compose.yml)