Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jtsylve--re-mcp/badge.svg)](/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

i

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)

  1. # RE-MCP
  2. 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.
  3. 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.
  4. ## Backends
  5. | Backend | Package | Requirements |
  6. |---------|---------|--------------|
  7. | **IDA Pro** | [`re-mcp-ida`](packages/re-mcp-ida/) | IDA Pro 9+ with a valid license |
  8. | **Ghidra** | [`re-mcp-ghidra`](packages/re-mcp-ghidra/) | Ghidra 12+, JDK 21+ |
  9. 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).
  10. ## Requirements
  11. - Python 3.12+
  12. - [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
  13. - macOS, Windows, or Linux
  14. - At least one supported backend installed on the same machine
  15. ## Installation
  16. Install individual backend packages directly, or install `re-mcp` and select a backend with `--backend`:
  17. ```bash
  18. # Individual backend packages (each provides its own CLI)
  19. uv tool install re-mcp-ida
  20. uv tool install re-mcp-ghidra
  21. # Or install the core package and use --backend to select
  22. uv tool install re-mcp --with re-mcp-ida --with re-mcp-ghidra
  23. ```
  24. With pip:
  25. ```bash
  26. pip install re-mcp-ida # IDA only
  27. pip install re-mcp-ghidra # Ghidra only
  28. pip install re-mcp re-mcp-ida re-mcp-ghidra # Unified CLI with both backends
  29. ```
  30. ### From source
  31. ```bash
  32. git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp
  33. uv sync
  34. ```
  35. Or with pip:
  36. ```bash
  37. git clone https://github.com/jtsylve/ida-mcp && cd ida-mcp
  38. pip install -e packages/re-mcp-core -e packages/re-mcp-ida -e packages/re-mcp-ghidra
  39. ```
  40. ### Finding IDA Pro
  41. The IDA backend looks for your IDA Pro installation in the following order:
  42. 1. **`IDADIR` environment variable** — checked first; set this if IDA is in a non-standard location.
  43. 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.
  44. 3. **Platform-specific default paths:**
  45. | Platform | Default search paths |
  46. |----------|---------------------|
  47. | macOS | `/Applications/IDA Professional *.app/Contents/MacOS` |
  48. | Windows | `C:\Program Files\IDA Professional 9.3`, `C:\Program Files\IDA Pro 9.3`, and `Program Files (x86)` equivalents |
  49. | Linux | `/opt/ida-pro-9.3`, `/opt/idapro-9.3`, `/opt/ida-9.3`, `~/ida-pro-9.3`, `~/idapro-9.3` |
  50. 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.
  51. ### Finding Ghidra
  52. The Ghidra backend looks for your Ghidra installation in the following order:
  53. 1. **`GHIDRA_INSTALL_DIR` environment variable** — checked first; set this if Ghidra is in a non-standard location.
  54. 2. **Config file** — `ghidra-install-dir` in `~/.ghidra/ghidra-config.json`.
  55. 3. **Platform-specific default paths:**
  56. | Platform | Default search paths |
  57. |----------|---------------------|
  58. | macOS | `/Applications/ghidra_*`, `~/ghidra_*` |
  59. | Windows | `C:\ghidra_*`, `~/ghidra_*` |
  60. | Linux | `/opt/ghidra_*`, `/usr/local/ghidra_*`, `~/ghidra_*` |
  61. ## Usage
  62. ### Running the server
  63. Each backend has its own CLI, or use the unified `re-mcp` command with `--backend`:
  64. ```bash
  65. # Individual backend CLIs
  66. uvx re-mcp-ida
  67. uvx re-mcp-ghidra
  68. # Unified CLI (requires backend package installed alongside)
  69. uvx --with re-mcp-ida re-mcp --backend ida
  70. uvx --with re-mcp-ghidra re-mcp --backend ghidra
  71. ```
  72. Both CLIs support the same subcommands:
  73. | Command | Description |
  74. |---------|-------------|
  75. | `<backend>` (or `<backend> stdio`) | Direct stdio mode — single-session, workers die on disconnect (default) |
  76. | `<backend> proxy` | Stdio proxy that auto-spawns a persistent HTTP daemon |
  77. | `<backend> serve` | Start the HTTP daemon directly (for manual daemon management) |
  78. | `<backend> stop` | Gracefully shut down a running daemon |
  79. | `<backend> backends` | List installed backends (most useful with the unified `re-mcp` CLI) |
  80. The default mode runs a direct stdio server — the simplest transport, widely supported across MCP clients. Workers die when the client disconnects.
  81. 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`).
  82. ### Running without installing
  83. ```bash
  84. # Individual backend packages
  85. IDADIR=/path/to/ida uvx re-mcp-ida
  86. GHIDRA_INSTALL_DIR=/path/to/ghidra uvx re-mcp-ghidra
  87. # Unified package
  88. IDADIR=/path/to/ida uvx --with re-mcp-ida re-mcp --backend ida
  89. GHIDRA_INSTALL_DIR=/path/to/ghidra uvx --with re-mcp-ghidra re-mcp --backend ghidra
  90. ```
  91. ```powershell
  92. # Individual backend packages
  93. $env:IDADIR = "C:\Program Files\IDA Professional 9.3"
  94. uvx re-mcp-ida
  95. $env:GHIDRA_INSTALL_DIR = "C:\ghidra_12.0.3_PUBLIC"
  96. uvx re-mcp-ghidra
  97. # Unified package
  98. $env:IDADIR = "C:\Program Files\IDA Professional 9.3"
  99. uvx --with re-mcp-ida re-mcp --backend ida
  100. ```
  101. ### MCP client configuration
  102. Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
  103. **IDA backend:**
  104. ```json
  105. {
  106. "mcpServers": {
  107. "ida": {
  108. "command": "uvx",
  109. "args": ["re-mcp-ida"]
  110. }
  111. }
  112. }
  113. ```
  114. **Ghidra backend:**
  115. ```json
  116. {
  117. "mcpServers": {
  118. "ghidra": {
  119. "command": "uvx",
  120. "args": ["re-mcp-ghidra"]
  121. }
  122. }
  123. }
  124. ```
  125. **Both backends simultaneously:**
  126. ```json
  127. {
  128. "mcpServers": {
  129. "ida": {
  130. "command": "uvx",
  131. "args": ["re-mcp-ida"]
  132. },
  133. "ghidra": {
  134. "command": "uvx",
  135. "args": ["re-mcp-ghidra"]
  136. }
  137. }
  138. }
  139. ```
  140. **Using the unified `re-mcp` CLI (when installed via `uv tool install re-mcp --with re-mcp-ida`):**
  141. ```json
  142. {
  143. "mcpServers": {
  144. "ida": {
  145. "command": "re-mcp",
  146. "args": ["--backend", "ida"]
  147. }
  148. }
  149. }
  150. ```
  151. If the backend command is installed on your `PATH` (e.g. via `pip install`), use it directly:
  152. ```json
  153. {
  154. "mcpServers": {
  155. "ida": {
  156. "command": "re-mcp-ida"
  157. }
  158. }
  159. }
  160. ```
  161. If the command isn't on your `PATH`, use the full path to the executable:
  162. ```json
  163. {
  164. "mcpServers": {
  165. "ida": {
  166. "command": "/home/user/.pyenv/versions/<version>/bin/re-mcp-ida"
  167. }
  168. }
  169. }
  170. ```
  171. If the backend (IDA or Ghidra) isn't in a default location, add the install directory via the `env` key:
  172. ```json
  173. {
  174. "mcpServers": {
  175. "ida": {
  176. "command": "uvx",
  177. "args": ["re-mcp-ida"],
  178. "env": {
  179. "IDADIR": "/path/to/ida"
  180. }
  181. },
  182. "ghidra": {
  183. "command": "uvx",
  184. "args": ["re-mcp-ghidra"],
  185. "env": {
  186. "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
  187. }
  188. }
  189. }
  190. }
  191. ```
  192. **Connecting to a running daemon directly:**
  193. 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.
  194. State file locations:
  195. - **macOS:** `~/Library/Application Support/<backend>/daemon.json`
  196. - **Linux:** `$XDG_STATE_HOME/<backend>/daemon.json` (defaults to `~/.local/state/<backend>/daemon.json`)
  197. - **Windows:** `%LOCALAPPDATA%\<backend>\daemon.json`
  198. Where `<backend>` is `re-mcp-ida` or `re-mcp-ghidra`.
  199. ```json
  200. {
  201. "mcpServers": {
  202. "ida": {
  203. "type": "streamable-http",
  204. "url": "http://127.0.0.1:<port>/mcp",
  205. "headers": {
  206. "Authorization": "Bearer <token>"
  207. }
  208. }
  209. }
  210. }
  211. ```
  212. ### Basic workflow
  213. 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
  214. 2. **Analyze** — use the available tools (list functions, decompile, search strings, read bytes, etc.)
  215. 3. **Close** — call `close_database` when done (auto-saves by default)
  216. 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.
  217. ### Multi-database mode
  218. 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`).
  219. ```
  220. open_database("first.bin") # spawns worker (returns immediately)
  221. wait_for_analysis(database="first") # blocks until ready
  222. open_database("second.bin") # spawns second worker
  223. wait_for_analysis(database="second") # blocks until ready
  224. decompile_function(address="main", database="first") # targets first
  225. close_database(database="second") # closes second
  226. ```
  227. ### Environment variables
  228. Each backend uses its own environment variable prefix (`IDA_MCP_` or `GHIDRA_MCP_`). The table below uses `<PREFIX>` as a placeholder.
  229. **Backend installation:**
  230. | Variable | Backend | Default | Description |
  231. |----------|---------|---------|-------------|
  232. | `IDADIR` | IDA | *(auto-detected)* | Path to IDA Pro installation directory |
  233. | `GHIDRA_INSTALL_DIR` | Ghidra | *(auto-detected)* | Path to Ghidra installation directory |
  234. **Shared settings** (replace `<PREFIX>` with `IDA_MCP_` or `GHIDRA_MCP_`):
  235. | Variable | Default | Description |
  236. |----------|---------|-------------|
  237. | `<PREFIX>MAX_WORKERS` | *(unlimited)* | Maximum simultaneous databases (clamped to 1-8 when set) |
  238. | `<PREFIX>LOG_LEVEL` | `WARNING` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) — output goes to stderr |
  239. | `<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. |
  240. | `<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). |
  241. | `<PREFIX>DISABLE_EXECUTE` | *(unset)* | Set to `1`, `true`, `yes`, or `on` to hide the `execute` meta-tool (sandboxed Python code mode) |
  242. | `<PREFIX>DISABLE_BATCH` | *(unset)* | Set to `1`, `true`, `yes`, or `on` to hide the `batch` meta-tool |
  243. | `<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). |
  244. **IDA-only settings:**
  245. | Variable | Default | Description |
  246. |----------|---------|-------------|
  247. | `IDA_MCP_ALLOW_SCRIPTS` | *(unset)* | Set to `1`, `true`, or `yes` to enable the `run_script` tool for arbitrary IDAPython execution |
  248. ## Tools
  249. 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:
  250. - **`search_tools`** — regex search over non-pinned tool names, descriptions, and tags (pinned tools are already visible).
  251. - **`get_schema`** — parameter schemas and return shapes for tools by name.
  252. - **`call`** — lightweight proxy for calling any tool by name, including hidden tools not in the client tool list.
  253. - **`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.
  254. - **`batch`** — sequential multi-tool execution with per-item error collection and progress reporting (up to 50 operations per call).
  255. 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.
  256. The full tool catalog spans these areas:
  257. - **Database** — open/close/save/list databases, file region mapping, metadata
  258. - **Functions** — list, query, decompile, disassemble, rename, prototypes, chunks, stack frames
  259. - **Decompiler** — pseudocode variable renaming/retyping, decompiler comments, microcode
  260. - **Ctree** — AST exploration and pattern matching
  261. - **Cross-References** — xref queries, call graphs, xref creation/deletion
  262. - **Imports & Exports** — imported functions, exported symbols, entry point listing and manipulation
  263. - **Search** — string extraction, byte patterns, text in disassembly, immediate values, string-to-code references, string list rebuilding
  264. - **Types & Structures** — local types, structs, enums, type parsing and application, source declarations
  265. - **Instructions & Operands** — decode instructions, resolve operand values, change operand display format
  266. - **Control Flow** — basic blocks, CFG edges, switch/jump tables
  267. - **Data** — raw byte reading, hex dumps, segment listing, pointer tables
  268. - **Patching** — byte patching, instruction assembly, function/code creation, data loading
  269. - **Data Definition** — define bytes, words, dwords, qwords, floats, doubles, strings, and arrays
  270. - **Segments** — create, modify, and rebase segments
  271. - **Names & Comments** — rename addresses, manage comments (get, set, and append)
  272. - **Demangling** — C++ symbol name demangling
  273. - **Analysis** — auto-analysis, fixups, exception handlers, segment registers
  274. - **Address Metadata** — source line numbers, analysis flags, library item marking
  275. - **Register Tracking** — register and stack pointer value tracking
  276. - **Register Variables** — register-to-name mappings within functions
  277. - **Signatures** — FLIRT signatures/type libraries (IDA), Function ID/data type archives (Ghidra)
  278. - **Export** — batch decompilation/disassembly, output file generation
  279. - **Snapshots** — take, list, and restore database snapshots
  280. - **Processor** — architecture info, register names, instruction classification
  281. - **Bookmarks** — marked-position management
  282. - **Colors** — address/function coloring
  283. - **Undo** — undo/redo operations
  284. - **Directory Tree** — folder organization
  285. - **Utility** — number conversion, expression evaluation, scripting
  286. 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.
  287. See [docs/tools.md](docs/tools.md) for the complete tools reference.
  288. ## Resources
  289. The server exposes [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) — read-only, cacheable endpoints for structured database context:
  290. - **Static binary data** — imports, exports, entry points (with regex search variants)
  291. - **Aggregate snapshot** — statistics (function/segment/entry point/string/name counts, code coverage)
  292. - **Supervisor** — `<scheme>://databases` lists all open databases with worker state
  293. The URI scheme is `ida://` for the IDA backend and `ghidra://` for the Ghidra backend.
  294. ## Prompts
  295. 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.
  296. - **`survey_binary`** — binary triage producing an executive summary
  297. - **`analyze_function`** — full single-function analysis with decompilation, data flow, and behavior summary
  298. - **`diff_before_after`** — preview the effect of renaming/retyping on decompiler output
  299. - **`classify_functions`** — categorize functions by behavioral pattern
  300. - **`find_crypto_constants`** — scan for known cryptographic constants
  301. - **`auto_rename_strings`** — suggest function renames based on string references
  302. - **`apply_abi`** — apply known ABI type information to identified functions
  303. - **`export_idc_script`** — generate a script that reproduces user annotations
  304. ## Architecture
  305. The project is a monorepo with three packages:
  306. - [`re-mcp-core`](packages/re-mcp-core/) — shared supervisor infrastructure, transport, and common utilities
  307. - [`re-mcp-ida`](packages/re-mcp-ida/) — IDA Pro backend
  308. - [`re-mcp-ghidra`](packages/re-mcp-ghidra/) — Ghidra backend
  309. See [docs/architecture.md](docs/architecture.md) for detailed architecture documentation.
  310. ## Development
  311. ```bash
  312. # With uv (recommended)
  313. uv sync # Install dependencies
  314. uv run ruff check packages/ # Lint
  315. uv run ruff format packages/ # Format
  316. uv run ruff check --fix packages/ # Lint with auto-fix
  317. # With pip
  318. pip install -e packages/re-mcp-core -e packages/re-mcp-ida -e packages/re-mcp-ghidra
  319. pip install pre-commit pytest pytest-asyncio ruff jsonschema
  320. ruff check packages/
  321. ruff format packages/
  322. ruff check --fix packages/
  323. ```
  324. 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.
  325. ## License
  326. This project is dual-licensed under the [MIT License](LICENSES/MIT.txt) and [Apache License 2.0](LICENSES/Apache-2.0.txt).
  327. © 2026 Joe T. Sylve, Ph.D.
  328. This project is [REUSE compliant](https://reuse.software/).
  329. ---
  330. *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 in

Free to use. If it’s helped, pass it on.