Skip to content
Back to search

ida-pro-mcp

AI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.

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/mrexodia--ida-pro-mcp/badge.svg)](/listings/mrexodia--ida-pro-mcp)

HTML

<a href="/listings/mrexodia--ida-pro-mcp"><img src="/api/listings/mrexodia--ida-pro-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.

To install the latest IDA Pro MCP in Claude Code:

claude plugin marketplace add mrexodia/claude-marketplace
claude plugin uninstall ida-pro-mcp@mrexodia
claude plugin install ida-pro-mcp@mrexodia

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.

.claude-plugin/plugin.json · Manifest · 17 lines
  1. {
  2. "name": "ida-pro-mcp",
  3. "version": "0.1.0",
  4. "description": "AI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.",
  5. "mcpServers": {
  6. "idalib": {
  7. "command": "uv",
  8. "args": [
  9. "run",
  10. "--project",
  11. "${CLAUDE_PLUGIN_ROOT}",
  12. "idalib-mcp",
  13. "--stdio"
  14. ]
  15. }
  16. }
  17. }
README.md · README · 433 lines
  1. # IDA Pro MCP
  2. > [!IMPORTANT]
  3. > **I recommend using the [Official Hex-Rays IDA MCP Server](https://github.com/HexRaysSA/ida-mcp) instead!**
  4. >
  5. > See the [announcement blog post](https://hex-rays.com/blog/hex-rays-ida-mcp-server) for more information.
  6. Simple [MCP Server](https://modelcontextprotocol.io/introduction) to allow vibe reversing in IDA Pro.
  7. https://github.com/user-attachments/assets/6ebeaa92-a9db-43fa-b756-eececce2aca0
  8. The binaries and prompt for the video are available in the [mcp-reversing-dataset](https://github.com/mrexodia/mcp-reversing-dataset) repository.
  9. ## Prerequisites
  10. - [Python](https://www.python.org/downloads/) (**3.11 or higher**)
  11. - Use `idapyswitch` to switch to the newest Python version
  12. - [IDA Pro](https://hex-rays.com/ida-pro) (8.3 or higher, 9 recommended), **IDA Free is not supported**
  13. - Supported MCP Client (pick one you like)
  14. - [Amazon Q Developer CLI](https://aws.amazon.com/q/developer/)
  15. - [Augment Code](https://www.augmentcode.com/)
  16. - [Claude](https://claude.ai/download)
  17. - [Claude Code](https://claude.com/product/claude-code)
  18. - [Cline](https://cline.bot)
  19. - [Codex](https://github.com/openai/codex)
  20. - [Copilot CLI](https://docs.github.com/en/copilot)
  21. - [Crush](https://github.com/charmbracelet/crush)
  22. - [Cursor](https://cursor.com)
  23. - [Gemini CLI](https://google-gemini.github.io/gemini-cli/)
  24. - [Kilo Code](https://kilo.ai/)
  25. - [Kiro](https://kiro.dev/)
  26. - [LM Studio](https://lmstudio.ai/)
  27. - [Opencode](https://opencode.ai/)
  28. - [Qodo Gen](https://www.qodo.ai/)
  29. - [Qwen Coder](https://qwenlm.github.io/qwen-code-docs/)
  30. - [Roo Code](https://roocode.com)
  31. - [Trae](https://trae.ai/)
  32. - [VS Code](https://code.visualstudio.com/)
  33. - [VS Code Insiders](https://code.visualstudio.com/insiders)
  34. - [Warp](https://www.warp.dev/)
  35. - [Windsurf](https://windsurf.com)
  36. - [Zed](https://zed.dev/)
  37. - [Kimi Code](https://moonshotai.github.io/kimi-code/en/)
  38. - [Other MCP Clients](https://modelcontextprotocol.io/clients#example-clients): Run `ida-pro-mcp --config` to get the JSON config for your client.
  39. **Note**: This requires having idalib activated globally and [uv](https://astral.sh/uv) installed:
  40. ```bash
  41. # windows
  42. uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"
  43. # macos
  44. uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"
  45. # linux
  46. uv run "/path/to/idapro-9.3/idalib/python/py-activate-idalib.py"
  47. ```
  48. ## Installation (Claude Code)
  49. To install the latest IDA Pro MCP in Claude Code:
  50. ```bash
  51. claude plugin marketplace add mrexodia/claude-marketplace
  52. claude plugin uninstall ida-pro-mcp@mrexodia
  53. claude plugin install ida-pro-mcp@mrexodia
  54. ```
  55. ## Installation (Codex)
  56. To install the latest IDA Pro MCP in Codex:
  57. ```bash
  58. codex plugin marketplace add mrexodia/codex-marketplace
  59. codex plugin remove ida-pro-mcp@mrexodia
  60. codex plugin add ida-pro-mcp@mrexodia
  61. ```
  62. ## Installation (Kimi Code)
  63. To install the latest IDA Pro MCP in Kimi Code, run this slash command in the chat:
  64. ```
  65. /plugins install https://github.com/mrexodia/ida-pro-mcp/tree/main
  66. /reload
  67. ```
  68. This installs the `idalib` MCP server and the `idapython` skill. Plugins are copied to
  69. `$KIMI_CODE_HOME/plugins/managed/`, so `uv` must be on your `PATH`. The first session after
  70. installing is slower, because `uv` resolves the dependencies before the server responds.
  71. ## Installation (GUI)
  72. **Note**: the MCP plugin is no longer recommended and will eventually be deprecated. Use `idalib-mcp` instead.
  73. If you want to configure the MCP server manually from the IDA GUI:
  74. ```sh
  75. pip uninstall ida-pro-mcp
  76. pip install https://github.com/mrexodia/ida-pro-mcp/archive/refs/heads/main.zip
  77. ```
  78. Configure the MCP servers and install the IDA Plugin:
  79. ```
  80. ida-pro-mcp --install
  81. ```
  82. **Important**: Make sure you completely restart IDA and your MCP client for the installation to take effect. Some clients (like Claude) run in the background and need to be quit from the tray icon.
  83. ## Prompt Engineering
  84. LLMs are prone to hallucinations and you need to be specific with your prompting. For reverse engineering the conversion between integers and bytes are especially problematic. Below is a minimal example prompt, feel free to start a discussion or open an issue if you have good results with a different prompt:
  85. ```md
  86. Your task is to analyze a crackme in IDA Pro. You can use the MCP tools to retrieve information. In general use the following strategy:
  87. - Inspect the decompilation and add comments with your findings
  88. - Rename variables to more sensible names
  89. - Change the variable and argument types if necessary (especially pointer and array types)
  90. - Change function names to be more descriptive
  91. - If more details are necessary, disassemble the function and add comments with your findings
  92. - NEVER convert number bases yourself. Use the `int_convert` MCP tool if needed!
  93. - Do not attempt brute forcing, derive any solutions purely from the disassembly and simple python scripts
  94. - Create a report.md with your findings and steps taken at the end
  95. - When you find a solution, prompt to user for feedback with the password you found
  96. ```
  97. This prompt was just the first experiment, please share if you found ways to improve the output!
  98. Another prompt by [@can1357](https://github.com/can1357):
  99. ```md
  100. Your task is to create a complete and comprehensive reverse engineering analysis. Reference AGENTS.md to understand the project goals and ensure the analysis serves our purposes.
  101. Use the following systematic methodology:
  102. 1. **Decompilation Analysis**
  103. - Thoroughly inspect the decompiler output
  104. - Add detailed comments documenting your findings
  105. - Focus on understanding the actual functionality and purpose of each component (do not rely on old, incorrect comments)
  106. 2. **Improve Readability in the Database**
  107. - Rename variables to sensible, descriptive names
  108. - Correct variable and argument types where necessary (especially pointers and array types)
  109. - Update function names to be descriptive of their actual purpose
  110. 3. **Deep Dive When Needed**
  111. - If more details are necessary, examine the disassembly and add comments with findings
  112. - Document any low-level behaviors that aren't clear from the decompilation alone
  113. - Use sub-agents to perform detailed analysis
  114. 4. **Important Constraints**
  115. - NEVER convert number bases yourself - use the int_convert MCP tool if needed
  116. - Use MCP tools to retrieve information as necessary
  117. - Derive all conclusions from actual analysis, not assumptions
  118. 5. **Documentation**
  119. - Produce comprehensive RE/*.md files with your findings
  120. - Document the steps taken and methodology used
  121. - When asked by the user, ensure accuracy over previous analysis file
  122. - Organize findings in a way that serves the project goals outlined in AGENTS.md or CLAUDE.md
  123. ```
  124. Live stream discussing prompting and showing some real-world malware analysis:
  125. [![](https://img.youtube.com/vi/iFxNuk3kxhk/0.jpg)](https://www.youtube.com/watch?v=iFxNuk3kxhk)
  126. ## Tips for Enhancing LLM Accuracy
  127. Large Language Models (LLMs) are powerful tools, but they can sometimes struggle with complex mathematical calculations or exhibit "hallucinations" (making up facts). Make sure to tell the LLM to use the `int_convert` MCP tool and you might also need [math-mcp](https://github.com/EthanHenrickson/math-mcp) for certain operations.
  128. Another thing to keep in mind is that LLMs will not perform well on obfuscated code. Before trying to use an LLM to solve the problem, take a look around the binary and spend some time (automatically) removing the following things:
  129. - String encryption
  130. - Import hashing
  131. - Control flow flattening
  132. - Code encryption
  133. - Anti-decompilation tricks
  134. You should also use a tool like Lumina or FLIRT to try and resolve all the open source library code and the C++ STL, this will further improve the accuracy.
  135. ## Transports & Headless MCP
  136. You can run an SSE server to connect to the user interface like this:
  137. ```sh
  138. uv run ida-pro-mcp --transport http://127.0.0.1:8744/sse
  139. ```
  140. After installing [`idalib`](https://docs.hex-rays.com/core/idalib/getting-started) you can also run a headless MCP server. You can start with an initial binary:
  141. ```sh
  142. uv run idalib-mcp --host 127.0.0.1 --port 8745 path/to/executable
  143. ```
  144. Or start without a binary and open arbitrary files later with `idb_open(...)`:
  145. ```sh
  146. uv run idalib-mcp --host 127.0.0.1 --port 8745
  147. ```
  148. For stdio-based clients, use:
  149. ```sh
  150. uv run idalib-mcp --stdio
  151. ```
  152. Database workers are persistent: each one runs as a detached process that
  153. outlives the supervisor that spawned it. When a new supervisor (over stdio
  154. or HTTP) calls `idb_open` for a binary that is already open under a worker
  155. on this host, the supervisor adopts that worker transparently — there is
  156. no separate "shared" mode to enable. Workers self-exit when no request has
  157. hit them for an idle interval.
  158. _Note_: The `idalib` feature was contributed by [Willi Ballenthin](https://github.com/williballenthin).
  159. ## Headless idalib Session Model
  160. `idalib-mcp` is a supervisor that keeps each open database in its own idalib worker process. Workers register themselves in a host-local discovery directory and outlive the supervisor that spawned them; any subsequent supervisor that wants the same path adopts the running worker. A worker self-exits when no request has hit it for its idle TTL (default 1 hour). Call `idb_close` to release a worker eagerly (freeing a slot toward `--max-workers`), adopted GUI/worker instances are detached rather than killed.
  161. `idb_open` picks the backend via its `mode` parameter:
  162. - `prefer_headless` (default): spawn an idalib worker (or adopt one that already has the file open).
  163. - `force_headless`: same, but never adopt a running GUI even if one has the file.
  164. - `prefer_gui`: adopt a running GUI for the file; otherwise spawn an idalib worker.
  165. - `force_gui`: adopt a running GUI for the file; otherwise launch a new IDA GUI process.
  166. Every tool call must carry an explicit `database` argument. There is no implicit "current database" — callers name the session they want to operate on.
  167. ```sh
  168. uv run idalib-mcp --stdio --max-workers 4
  169. ```
  170. Typical flow:
  171. ```python
  172. idb_open("/path/to/binary_a.exe", preferred_session_id="binary_a")
  173. idb_open("/path/to/library.dll", preferred_session_id="library")
  174. decompile("main", database="binary_a")
  175. xrefs_to("ImportantExport", database="library")
  176. ```
  177. `database` must be the session ID returned by `idb_open` (or shown in `idb_list`); filenames and paths are not accepted.
  178. ### Management tools
  179. - `idb_open(input_path, mode="prefer_headless", run_auto_analysis=True, build_caches=True, init_hexrays=True, preferred_session_id="")`: Open a binary, warm up subsystems (strings cache, Hex-Rays), and return its session ID. If a worker or GUI for this path is already running on the host, that instance is adopted and `preferred_session_id` is ignored.
  180. - `idb_list()`: List open sessions and running GUI IDA instances. Each entry has `adopted` (True if this supervisor manages it, False for GUIs/workers discovered but not yet opened via `idb_open`), `backend` (`worker` or `gui`), `is_active`, and process IDs.
  181. - `idb_close(database, save=True)`: Save (optionally), unregister the session, and terminate its owned worker, freeing a slot toward `--max-workers`. Adopted GUI/worker instances are detached, not killed.
  182. - `idb_save(session_id, path="")`: Save a session's IDB to disk. Forwarded as a regular worker tool (`database=<id>` injected) — same signature in both backends.
  183. - Per-database health: call `server_health(database=<id>)` (forwarded). `idb_list()` reports `is_active` from the supervisor's TCP/RPC probe.
  184. Worker controls:
  185. - `--max-workers N`: maximum simultaneous database workers (`0` = unlimited, default `4`).
  186. - `IDA_MCP_MAX_WORKERS`: environment default for `--max-workers`.
  187. The bundled Codex plugin forwards the runtime's `IDA_MCP_*` configuration variables from the Codex host environment:
  188. - Capacity and lifecycle: `IDA_MCP_MAX_WORKERS`, `IDA_MCP_OPEN_TIMEOUT`, `IDA_MCP_WEDGED_GRACE_SEC`, `IDA_MCP_WORKER_CALL_TIMEOUT`.
  189. - Health probes: `IDA_MCP_HEALTH_TCP_TIMEOUT`, `IDA_MCP_HEALTH_RPC_TIMEOUT`, `IDA_MCP_HEALTH_RETRIES`, `IDA_MCP_HEALTH_RETRY_BACKOFF`.
  190. - Worker behavior: `IDA_MCP_TOOL_TIMEOUT_SEC`, `IDA_MCP_ANALYSIS_PROMPT`, `IDA_MCP_URL`.
  191. - Request logging: `IDA_MCP_LOG_REQUESTS`, `IDA_MCP_LOG_SKIP_METHODS`.
  192. ## MCP Resources
  193. **Resources** represent browsable state (read-only data) following MCP's philosophy.
  194. **Core IDB State:**
  195. - `ida://idb/metadata` - IDB file info (path, arch, base, size, hashes)
  196. - `ida://idb/segments` - Memory segments with permissions
  197. - `ida://idb/entrypoints` - Entry points (main, TLS callbacks, etc.)
  198. **UI State:**
  199. - `ida://cursor` - Current cursor position and function
  200. - `ida://selection` - Current selection range
  201. **Type Information:**
  202. - `ida://types` - All local types
  203. - `ida://structs` - All structures/unions
  204. - `ida://struct/{name}` - Structure definition with fields
  205. **Lookups:**
  206. - `ida://import/{name}` - Import details by name
  207. - `ida://export/{name}` - Export details by name
  208. - `ida://xrefs/from/{addr}` - Cross-references from address
  209. ## Core Functions
  210. - `lookup_funcs(queries)`: Get function(s) by address or name (auto-detects, accepts list or comma-separated string).
  211. - `int_convert(inputs)`: Convert numbers to different formats (decimal, hex, bytes, ASCII, binary).
  212. - `list_funcs(queries)`: List functions (paginated, filtered).
  213. - `list_globals(queries)`: List global variables (paginated, filtered).
  214. - `imports(offset, count)`: List all imported symbols with module names (paginated).
  215. - `decompile(addr)`: Decompile function at the given address.
  216. - `disasm(addr)`: Disassemble function with full details (arguments, stack frame, etc).
  217. - `xrefs_to(addrs)`: Get all cross-references to address(es).
  218. - `xrefs_to_field(queries)`: Get cross-references to specific struct field(s).
  219. - `callees(addrs)`: Get functions called by function(s) at address(es).
  220. ## Modification Operations
  221. - `add_bookmark(addr, name, prefix)`: Add or replace the IDA bookmark at an address; set `prefix=""` for no prefix.
  222. - `set_comments(items)`: Set comments at address(es) in both disassembly and decompiler views.
  223. - `patch_asm(items)`: Patch assembly instructions at address(es).
  224. - `declare_type(decls)`: Declare C type(s) in the local type library.
  225. - `define_func(items)`: Define function(s) at address(es). Optionally specify `end` for explicit bounds.
  226. - `define_code(items)`: Convert bytes to code instruction(s) at address(es).
  227. - `undefine(items)`: Undefine item(s) at address(es), converting back to raw bytes. Optionally specify `end` or `size`.
  228. ## Memory Reading Operations
  229. - `get_bytes(addrs)`: Read raw bytes at address(es).
  230. - `get_int(queries)`: Read integer values using ty (i8/u64/i16le/i16be/etc).
  231. - `get_string(addrs)`: Read null-terminated string(s).
  232. - `get_global_value(queries)`: Read global variable value(s) by address or name (auto-detects, compile-time values).
  233. ## Stack Frame Operations
  234. - `stack_frame(addrs)`: Get stack frame variables for function(s).
  235. - `declare_stack(items)`: Create stack variable(s) at specified offset(s).
  236. - `delete_stack(items)`: Delete stack variable(s) by name.
  237. ## Structure Operations
  238. - `read_struct(queries)`: Read structure field values at specific address(es).
  239. - `search_structs(filter)`: Search structures by name pattern.
  240. ## Debugger Operations (Extension)
  241. Debugger tools are hidden by default. Enable with `?ext=dbg` query parameter:
  242. ```
  243. http://127.0.0.1:13337/mcp?ext=dbg
  244. ```
  245. **Control:**
  246. - `dbg_start()`: Start debugger process.
  247. - `dbg_exit()`: Exit debugger process.
  248. - `dbg_continue()`: Continue execution.
  249. - `dbg_run_to(addr)`: Run to address.
  250. - `dbg_step_into()`: Step into instruction.
  251. - `dbg_step_over()`: Step over instruction.
  252. **Breakpoints:**
  253. - `dbg_bps()`: List all breakpoints.
  254. - `dbg_add_bp(addrs)`: Add breakpoint(s).
  255. - `dbg_delete_bp(addrs)`: Delete breakpoint(s).
  256. - `dbg_toggle_bp(items)`: Enable/disable breakpoint(s).
  257. **Registers:**
  258. - `dbg_regs()`: All registers, current thread.
  259. - `dbg_regs_all()`: All registers, all threads.
  260. - `dbg_regs_remote(tids)`: All registers, specific thread(s).
  261. - `dbg_gpregs()`: GP registers, current thread.
  262. - `dbg_gpregs_remote(tids)`: GP registers, specific thread(s).
  263. - `dbg_regs_named(names)`: Named registers, current thread.
  264. - `dbg_regs_named_remote(tid, names)`: Named registers, specific thread.
  265. **Stack & Memory:**
  266. - `dbg_stacktrace()`: Call stack with module/symbol info.
  267. - `dbg_read(regions)`: Read memory from debugged process.
  268. - `dbg_write(regions)`: Write memory to debugged process.
  269. ## Advanced Analysis Operations
  270. - `py_eval(code)`: Execute arbitrary Python code in IDA context (returns dict with result/stdout/stderr, supports Jupyter-style evaluation).
  271. - `analyze_funcs(addrs)`: Comprehensive function analysis (decompilation, assembly, xrefs, callees, callers, strings, constants, basic blocks).
  272. ## Pattern Matching & Search
  273. - `find_regex(queries)`: Search strings with case-insensitive regex (paginated).
  274. - `find_bytes(patterns, limit=1000, offset=0)`: Find byte pattern(s) in binary (e.g., "48 8B ?? ??"). Max limit: 10000.
  275. - `find_insns(sequences, limit=1000, offset=0)`: Find instruction sequence(s) in code. Max limit: 10000.
  276. - `find(type, targets, limit=1000, offset=0)`: Advanced search (immediate values, strings, data/code references). Max limit: 10000.
  277. ## Control Flow Analysis
  278. - `basic_blocks(addrs)`: Get basic blocks with successors and predecessors.
  279. ## Type Operations
  280. - `set_type(edits)`: Apply type(s) to functions, globals, locals, or stack variables.
  281. - `infer_types(addrs)`: Infer types at address(es) using Hex-Rays or heuristics.
  282. ## Export Operations
  283. - `export_funcs(addrs, format)`: Export function(s) in specified format (json, c_header, or prototypes).
  284. ## Graph Operations
  285. - `callgraph(roots, max_depth)`: Build call graph from root function(s) with configurable depth.
  286. ## Batch Operations
  287. - `rename(batch)`: Unified batch rename operation for functions, globals, locals, and stack variables (accepts dict with optional `func`, `data`, `local`, `stack` keys).
  288. - `patch(patches)`: Patch multiple byte sequences at once.
  289. - `put_int(items)`: Write integer values using ty (i8/u64/i16le/i16be/etc).
  290. **Key Features:**
  291. - **Type-safe API**: All functions use strongly-typed parameters with TypedDict schemas for better IDE support and LLM structured outputs
  292. - **Batch-first design**: Most operations accept both single items and lists
  293. - **Consistent error handling**: All batch operations return `[{..., error: null|string}, ...]`
  294. - **Cursor-based pagination**: Search functions return `cursor: {next: offset}` or `{done: true}` (default limit: 1000, enforced max: 10000 to prevent token overflow)
  295. - **Performance**: Strings are cached with MD5-based invalidation to avoid repeated `build_strlist` calls in large projects
  296. ## Development
  297. Adding new features is a super easy and streamlined process. All you have to do is add a new `@tool` function to the modular API files in `src/ida_pro_mcp/ida_mcp/api_*.py` and your function will be available in the MCP server without any additional boilerplate! Below is a video where I add the `get_metadata` function in less than 2 minutes (including testing):
  298. https://github.com/user-attachments/assets/951de823-88ea-4235-adcb-9257e316ae64
  299. To test the MCP server itself:
  300. ```sh
  301. npx -y @modelcontextprotocol/inspector
  302. ```
  303. This will open a web interface at http://localhost:5173 and allow you to interact with the MCP tools for testing.
  304. For testing I create a symbolic link to the IDA plugin and then POST a JSON-RPC request directly to `http://localhost:13337/mcp`. After [enabling symbolic links](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) you can run the following command:
  305. ```sh
  306. uv run ida-pro-mcp --install
  307. ```
  308. Generate the changelog of direct commits to `main`:
  309. ```sh
  310. git log --first-parent --no-merges 1.2.0..main "--pretty=- %s"
  311. ```

Ratings and comments

Sign in to rate this skill.

Sign in

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