re-mcp
A headless MCP server for IDA Pro and Ghidra
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jtsylve--re-mcp)HTML
<a href="/listings/jtsylve--re-mcp"><img src="/api/listings/jtsylve--re-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install individual backend packages directly, or install `re-mcp` and select a backend with `--backend`:
# Individual backend packages (each provides its own CLI) uv tool install re-mcp-ida uv tool install re-mcp-ghidra # Or install the core package and use --backend to select uv tool install re-mcp --with re-mcp-ida --with re-mcp-ghidra
With pip:
pip install re-mcp-ida # IDA only pip install re-mcp-ghidra # Ghidra only pip install re-mcp re-mcp-ida re-mcp-ghidra # Unified CLI with both backends
From source
git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp uv sync
Or with pip:
git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp pip install -e packages/re-mcp-core -e packages/re-mcp-ida -e packages/re-mcp-ghidra
Finding IDA Pro
The IDA backend looks for your IDA Pro installation in the following order:
1. **`IDADIR` environment variable** — checked first; set this if IDA is in a non-standard location. 2. **IDA's own config file** — `Paths.ida-install-dir` in `~/.idapro/ida-config.json` (macOS/Linux) or `%APPDATA%\Hex-Rays\IDA Pro\ida-config.json` (Windows). If the `IDAUSR` environment variable is set, it is used as the config directory instead. 3. **Platform-specific default paths:**
| Platform | Default search paths | |----------|---------------------| | macOS | `/Applications/IDA Professional *.app/Contents/MacOS` | | Windows | `C:\Program Files\IDA Professional 9.3`, `C:\Program Files\IDA Pro 9.3`, and `Program Files (x86)` equivalents | | Linux | `/opt/ida-pro-9.3`, `/opt/idapro-9.3`, `/opt/ida-9.3`, `~/ida-pro-9.3`, `~/idapro-9.3` |
The `idapro` package is loaded at runtime directly from your local IDA Pro installation — no extra setup steps or environment variables are needed if IDA is installed in a standard location.
Finding Ghidra
The Ghidra backend looks for your Ghidra installation in the following order:
1. **`GHIDRA_INSTALL_DIR` environment variable** — checked first; set this if Ghidra is in a non-standard location. 2. **Config file** — `ghidra-install-dir` in `~/.ghidra/ghidra-config.json`. 3. **Platform-specific default paths:**
| Platform | Default search paths | |----------|---------------------| | macOS | `/Applications/ghidra_*`, `~/ghidra_*` | | Windows | `C:\ghidra_*`, `~/ghidra_*` | | Linux | `/opt/ghidra_*`, `/usr/local/ghidra_*`, `~/ghidra_*` |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 435 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # RE-MCP
- A multi-backend reverse-engineering [MCP](https://modelcontextprotocol.io/) server. Exposes binary analysis capabilities from [IDA Pro](https://hex-rays.com/ida-pro/) and [Ghidra](https://ghidra-sre.org/) over the Model Context Protocol, letting LLMs drive reverse-engineering tools directly. Supports multiple simultaneous databases through a supervisor/worker architecture.
- Both backends are standalone servers, not plugins. They use headless APIs ([idalib](https://docs.hex-rays.com/release-notes/9_0#idalib-ida-as-a-library) for IDA, [pyghidra](https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/PyGhidra) for Ghidra) to run analysis engines without a GUI.
- ## Backends
- | Backend | Package | Requirements |
- |---------|---------|--------------|
- | **IDA Pro** | [`re-mcp-ida`](packages/re-mcp-ida/) | IDA Pro 9+ with a valid license |
- | **Ghidra** | [`re-mcp-ghidra`](packages/re-mcp-ghidra/) | Ghidra 12+, JDK 21+ |
- Both backends share a common tool interface — core analysis tools use the same names, parameters, and response shapes — so LLM workflows are portable across backends. Each backend also has tools for platform-specific features (e.g. IDA: file region mapping, executable rebuilding, IDC evaluation, IDAPython scripting; Ghidra: Function ID analysis, data type archives).
- ## Requirements
- - Python 3.12+
- - [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
- - macOS, Windows, or Linux
- - At least one supported backend installed on the same machine
- ## Installation
- Install individual backend packages directly, or install `re-mcp` and select a backend with `--backend`:
- ```bash
- # Individual backend packages (each provides its own CLI)
- uv tool install re-mcp-ida
- uv tool install re-mcp-ghidra
- # Or install the core package and use --backend to select
- uv tool install re-mcp --with re-mcp-ida --with re-mcp-ghidra
- ```
- With pip:
- ```bash
- pip install re-mcp-ida # IDA only
- pip install re-mcp-ghidra # Ghidra only
- pip install re-mcp re-mcp-ida re-mcp-ghidra # Unified CLI with both backends
- ```
- ### From source
- ```bash
- git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp
- uv sync
- ```
- Or with pip:
- ```bash
- git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp
- pip install -e packages/re-mcp-core -e packages/re-mcp-ida -e packages/re-mcp-ghidra
- ```
- ### Finding IDA Pro
- The IDA backend looks for your IDA Pro installation in the following order:
- 1. **`IDADIR` environment variable** — checked first; set this if IDA is in a non-standard location.
- 2. **IDA's own config file** — `Paths.ida-install-dir` in `~/.idapro/ida-config.json` (macOS/Linux) or `%APPDATA%\Hex-Rays\IDA Pro\ida-config.json` (Windows). If the `IDAUSR` environment variable is set, it is used as the config directory instead.
- 3. **Platform-specific default paths:**
- | Platform | Default search paths |
- |----------|---------------------|
- | macOS | `/Applications/IDA Professional *.app/Contents/MacOS` |
- | Windows | `C:\Program Files\IDA Professional 9.3`, `C:\Program Files\IDA Pro 9.3`, and `Program Files (x86)` equivalents |
- | Linux | `/opt/ida-pro-9.3`, `/opt/idapro-9.3`, `/opt/ida-9.3`, `~/ida-pro-9.3`, `~/idapro-9.3` |
- The `idapro` package is loaded at runtime directly from your local IDA Pro installation — no extra setup steps or environment variables are needed if IDA is installed in a standard location.
- ### Finding Ghidra
- The Ghidra backend looks for your Ghidra installation in the following order:
- 1. **`GHIDRA_INSTALL_DIR` environment variable** — checked first; set this if Ghidra is in a non-standard location.
- 2. **Config file** — `ghidra-install-dir` in `~/.ghidra/ghidra-config.json`.
- 3. **Platform-specific default paths:**
- | Platform | Default search paths |
- |----------|---------------------|
- | macOS | `/Applications/ghidra_*`, `~/ghidra_*` |
- | Windows | `C:\ghidra_*`, `~/ghidra_*` |
- | Linux | `/opt/ghidra_*`, `/usr/local/ghidra_*`, `~/ghidra_*` |
- ## Usage
- ### Running the server
- Each backend has its own CLI, or use the unified `re-mcp` command with `--backend`:
- ```bash
- # Individual backend CLIs
- uvx re-mcp-ida
- uvx re-mcp-ghidra
- # Unified CLI (requires backend package installed alongside)
- uvx --with re-mcp-ida re-mcp --backend ida
- uvx --with re-mcp-ghidra re-mcp --backend ghidra
- ```
- Both CLIs support the same subcommands:
- | Command | Description |
- |---------|-------------|
- | `<backend>` (or `<backend> stdio`) | Direct stdio mode — single-session, workers die on disconnect (default) |
- | `<backend> proxy` | Stdio proxy that auto-spawns a persistent HTTP daemon |
- | `<backend> serve` | Start the HTTP daemon directly (for manual daemon management) |
- | `<backend> stop` | Gracefully shut down a running daemon |
- | `<backend> backends` | List installed backends (most useful with the unified `re-mcp` CLI) |
- The default mode runs a direct stdio server — the simplest transport, widely supported across MCP clients. Workers die when the client disconnects.
- For persistent state across reconnections, use `<backend> proxy`. This mode auto-spawns a persistent HTTP daemon behind the scenes, handling port allocation and authentication transparently. Workers and database state survive client reconnections. The daemon shuts down automatically after 5 minutes of inactivity (configurable via `<PREFIX>IDLE_TIMEOUT`).
- ### Running without installing
- ```bash
- # Individual backend packages
- IDADIR=/path/to/ida uvx re-mcp-ida
- GHIDRA_INSTALL_DIR=/path/to/ghidra uvx re-mcp-ghidra
- # Unified package
- IDADIR=/path/to/ida uvx --with re-mcp-ida re-mcp --backend ida
- GHIDRA_INSTALL_DIR=/path/to/ghidra uvx --with re-mcp-ghidra re-mcp --backend ghidra
- ```
- ```powershell
- # Individual backend packages
- $env:IDADIR = "C:\Program Files\IDA Professional 9.3"
- uvx re-mcp-ida
- $env:GHIDRA_INSTALL_DIR = "C:\ghidra_12.0.3_PUBLIC"
- uvx re-mcp-ghidra
- # Unified package
- $env:IDADIR = "C:\Program Files\IDA Professional 9.3"
- uvx --with re-mcp-ida re-mcp --backend ida
- ```
- ### MCP client configuration
- Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
- **IDA backend:**
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "uvx",
- "args": ["re-mcp-ida"]
- }
- }
- }
- ```
- **Ghidra backend:**
- ```json
- {
- "mcpServers": {
- "ghidra": {
- "command": "uvx",
- "args": ["re-mcp-ghidra"]
- }
- }
- }
- ```
- **Both backends simultaneously:**
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "uvx",
- "args": ["re-mcp-ida"]
- },
- "ghidra": {
- "command": "uvx",
- "args": ["re-mcp-ghidra"]
- }
- }
- }
- ```
- **Using the unified `re-mcp` CLI (when installed via `uv tool install re-mcp --with re-mcp-ida`):**
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "re-mcp",
- "args": ["--backend", "ida"]
- }
- }
- }
- ```
- If the backend command is installed on your `PATH` (e.g. via `pip install`), use it directly:
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "re-mcp-ida"
- }
- }
- }
- ```
- If the command isn't on your `PATH`, use the full path to the executable:
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "/home/user/.pyenv/versions/<version>/bin/re-mcp-ida"
- }
- }
- }
- ```
- If the backend (IDA or Ghidra) isn't in a default location, add the install directory via the `env` key:
- ```json
- {
- "mcpServers": {
- "ida": {
- "command": "uvx",
- "args": ["re-mcp-ida"],
- "env": {
- "IDADIR": "/path/to/ida"
- }
- },
- "ghidra": {
- "command": "uvx",
- "args": ["re-mcp-ghidra"],
- "env": {
- "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
- }
- }
- }
- }
- ```
- **Connecting to a running daemon directly:**
- If you started the daemon manually with `<backend> serve`, the connection details (host, port, bearer token) are in the state file. Clients that support streamable HTTP can connect directly.
- State file locations:
- - **macOS:** `~/Library/Application Support/<backend>/daemon.json`
- - **Linux:** `$XDG_STATE_HOME/<backend>/daemon.json` (defaults to `~/.local/state/<backend>/daemon.json`)
- - **Windows:** `%LOCALAPPDATA%\<backend>\daemon.json`
- Where `<backend>` is `re-mcp-ida` or `re-mcp-ghidra`.
- ```json
- {
- "mcpServers": {
- "ida": {
- "type": "streamable-http",
- "url": "http://127.0.0.1:<port>/mcp",
- "headers": {
- "Authorization": "Bearer <token>"
- }
- }
- }
- }
- ```
- ### Basic workflow
- 1. **Open a binary** — call `open_database` with the path to a binary (or existing database file), then `wait_for_analysis` to block until it is ready
- 2. **Analyze** — use the available tools (list functions, decompile, search strings, read bytes, etc.)
- 3. **Close** — call `close_database` when done (auto-saves by default)
- Raw binaries must be in a writable directory since both backends create database files alongside them. When opening an existing database, the original binary does not need to be present.
- ### Multi-database mode
- Multiple databases can be open at the same time. By default, `open_database` keeps previously opened databases open. Pass `keep_open=False` to save and close databases owned by the current session before opening the new one. All tools except management tools (`open_database`, `close_database`, `save_database`, `list_databases`, `wait_for_analysis`, `list_targets`) require the `database` parameter (the stem ID returned by `open_database` or `list_databases`).
- ```
- open_database("first.bin") # spawns worker (returns immediately)
- wait_for_analysis(database="first") # blocks until ready
- open_database("second.bin") # spawns second worker
- wait_for_analysis(database="second") # blocks until ready
- decompile_function(address="main", database="first") # targets first
- close_database(database="second") # closes second
- ```
- ### Environment variables
- Each backend uses its own environment variable prefix (`IDA_MCP_` or `GHIDRA_MCP_`). The table below uses `<PREFIX>` as a placeholder.
- **Backend installation:**
- | Variable | Backend | Default | Description |
- |----------|---------|---------|-------------|
- | `IDADIR` | IDA | *(auto-detected)* | Path to IDA Pro installation directory |
- | `GHIDRA_INSTALL_DIR` | Ghidra | *(auto-detected)* | Path to Ghidra installation directory |
- **Shared settings** (replace `<PREFIX>` with `IDA_MCP_` or `GHIDRA_MCP_`):
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `<PREFIX>MAX_WORKERS` | *(unlimited)* | Maximum simultaneous databases (clamped to 1-8 when set) |
- | `<PREFIX>LOG_LEVEL` | `WARNING` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) — output goes to stderr |
- | `<PREFIX>LOG_DIR` | *(unset)* | Directory for per-run log files. Each component logs to `<dir>/<run_id>-<label>.log`, each worker to `<dir>/<run_id>-worker-<db>.log`, and each worker's raw stderr to `<dir>/<run_id>-worker-<db>.stderr`. When unset, logs go only to stderr. |
- | `<PREFIX>IDLE_TIMEOUT` | `300` | Idle auto-shutdown timeout in seconds for auto-spawned daemons. Set to `0` to disable. `<backend> serve` defaults to `0` (use `--idle-timeout=N` to override). |
- | `<PREFIX>DISABLE_EXECUTE` | *(unset)* | Set to `1`, `true`, `yes`, or `on` to hide the `execute` meta-tool (sandboxed Python code mode) |
- | `<PREFIX>DISABLE_BATCH` | *(unset)* | Set to `1`, `true`, `yes`, or `on` to hide the `batch` meta-tool |
- | `<PREFIX>DISABLE_TOOL_SEARCH` | *(unset)* | Set to `1`, `true`, `yes`, or `on` to disable server-side progressive tool disclosure — all tools become directly visible and callable, and the `search_tools` and `get_schema` meta-tools are removed. Useful with clients that provide their own tool deferral (e.g. Claude Code). |
- **IDA-only settings:**
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `IDA_MCP_ALLOW_SCRIPTS` | *(unset)* | Set to `1`, `true`, or `yes` to enable the `run_script` tool for arbitrary IDAPython execution |
- ## Tools
- To keep token usage manageable, only common analysis tools and management tools are directly visible to clients. The rest are discoverable and callable through meta-tools:
- - **`search_tools`** — regex search over non-pinned tool names, descriptions, and tags (pinned tools are already visible).
- - **`get_schema`** — parameter schemas and return shapes for tools by name.
- - **`call`** — lightweight proxy for calling any tool by name, including hidden tools not in the client tool list.
- - **`execute`** — sandboxed Python that chains multiple `await invoke(name, params)` calls in a single round trip. Supports `asyncio.gather` for parallel queries, loops, and conditional logic between calls.
- - **`batch`** — sequential multi-tool execution with per-item error collection and progress reporting (up to 50 operations per call).
- Management tools (`open_database`, `close_database`, `save_database`, `list_databases`, `wait_for_analysis`, `list_targets`) are always visible. Most must be called directly — `save_database` and `list_databases` are the exceptions, also callable through `call`, `execute`, and `batch` for use in multi-step workflows.
- The full tool catalog spans these areas:
- - **Database** — open/close/save/list databases, file region mapping, metadata
- - **Functions** — list, query, decompile, disassemble, rename, prototypes, chunks, stack frames
- - **Decompiler** — pseudocode variable renaming/retyping, decompiler comments, microcode
- - **Ctree** — AST exploration and pattern matching
- - **Cross-References** — xref queries, call graphs, xref creation/deletion
- - **Imports & Exports** — imported functions, exported symbols, entry point listing and manipulation
- - **Search** — string extraction, byte patterns, text in disassembly, immediate values, string-to-code references, string list rebuilding
- - **Types & Structures** — local types, structs, enums, type parsing and application, source declarations
- - **Instructions & Operands** — decode instructions, resolve operand values, change operand display format
- - **Control Flow** — basic blocks, CFG edges, switch/jump tables
- - **Data** — raw byte reading, hex dumps, segment listing, pointer tables
- - **Patching** — byte patching, instruction assembly, function/code creation, data loading
- - **Data Definition** — define bytes, words, dwords, qwords, floats, doubles, strings, and arrays
- - **Segments** — create, modify, and rebase segments
- - **Names & Comments** — rename addresses, manage comments (get, set, and append)
- - **Demangling** — C++ symbol name demangling
- - **Analysis** — auto-analysis, fixups, exception handlers, segment registers
- - **Address Metadata** — source line numbers, analysis flags, library item marking
- - **Register Tracking** — register and stack pointer value tracking
- - **Register Variables** — register-to-name mappings within functions
- - **Signatures** — FLIRT signatures/type libraries (IDA), Function ID/data type archives (Ghidra)
- - **Export** — batch decompilation/disassembly, output file generation
- - **Snapshots** — take, list, and restore database snapshots
- - **Processor** — architecture info, register names, instruction classification
- - **Bookmarks** — marked-position management
- - **Colors** — address/function coloring
- - **Undo** — undo/redo operations
- - **Directory Tree** — folder organization
- - **Utility** — number conversion, expression evaluation, scripting
- All tools include MCP [annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can distinguish safe reads from mutations and prompt for confirmation on destructive operations. Mutation tools return old values alongside new values for change tracking.
- See [docs/tools.md](docs/tools.md) for the complete tools reference.
- ## Resources
- The server exposes [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) — read-only, cacheable endpoints for structured database context:
- - **Static binary data** — imports, exports, entry points (with regex search variants)
- - **Aggregate snapshot** — statistics (function/segment/entry point/string/name counts, code coverage)
- - **Supervisor** — `<scheme>://databases` lists all open databases with worker state
- The URI scheme is `ida://` for the IDA backend and `ghidra://` for the Ghidra backend.
- ## Prompts
- The server provides [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts) — guided workflow templates that instruct the LLM to use tools in a structured sequence. Prompts are currently available for the IDA backend only.
- - **`survey_binary`** — binary triage producing an executive summary
- - **`analyze_function`** — full single-function analysis with decompilation, data flow, and behavior summary
- - **`diff_before_after`** — preview the effect of renaming/retyping on decompiler output
- - **`classify_functions`** — categorize functions by behavioral pattern
- - **`find_crypto_constants`** — scan for known cryptographic constants
- - **`auto_rename_strings`** — suggest function renames based on string references
- - **`apply_abi`** — apply known ABI type information to identified functions
- - **`export_idc_script`** — generate a script that reproduces user annotations
- ## Architecture
- The project is a monorepo with three packages:
- - [`re-mcp-core`](packages/re-mcp-core/) — shared supervisor infrastructure, transport, and common utilities
- - [`re-mcp-ida`](packages/re-mcp-ida/) — IDA Pro backend
- - [`re-mcp-ghidra`](packages/re-mcp-ghidra/) — Ghidra backend
- See [docs/architecture.md](docs/architecture.md) for detailed architecture documentation.
- ## Development
- ```bash
- # With uv (recommended)
- uv sync # Install dependencies
- uv run ruff check packages/ # Lint
- uv run ruff format packages/ # Format
- uv run ruff check --fix packages/ # Lint with auto-fix
- # With pip
- pip install -e packages/re-mcp-core -e packages/re-mcp-ida -e packages/re-mcp-ghidra
- pip install pre-commit pytest pytest-asyncio ruff jsonschema
- ruff check packages/
- ruff format packages/
- ruff check --fix packages/
- ```
- Pre-commit hooks run REUSE compliance checks, ruff lint (with `--fix --exit-non-zero-on-fix`), ruff format, idalib threading lint, and pytest on every commit.
- ## License
- This project is dual-licensed under the [MIT License](LICENSES/MIT.txt) and [Apache License 2.0](LICENSES/Apache-2.0.txt).
- © 2026 Joe T. Sylve, Ph.D.
- This project is [REUSE compliant](https://reuse.software/).
- ---
- *IDA Pro and Hex-Rays are trademarks of Hex-Rays SA. Ghidra is developed by the NSA. RE-MCP is an independent project and is not affiliated with or endorsed by Hex-Rays or the NSA.*
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.