IDA Pro MCP

Simple MCP Server to allow vibe reversing in IDA Pro.

https://github.com/user-attachments/assets/6ebeaa92-a9db-43fa-b756-eececce2aca0

The binaries and prompt for the video are available in the mcp-reversing-dataset repository.

Prerequisites

• Python (3.11 or higher)

  • Use idapyswitch to switch to the newest Python version

• IDA Pro (8.3 or higher, 9 recommended), IDA Free is not supported

• Supported MCP Client (pick one you like)

  • Amazon Q Developer CLI

  • Augment Code

  • Claude

  • Claude Code

  • Cline

  • Codex

  • Copilot CLI

  • Crush

  • Cursor

  • Gemini CLI

  • Kilo Code

  • Kiro

  • LM Studio

  • Opencode

  • Qodo Gen

  • Qwen Coder

  • Roo Code

  • Trae

  • VS Code

  • VS Code Insiders

  • Warp

  • Windsurf

  • Zed

  • Kimi Code

  • Other MCP Clients: Run ida-pro-mcp --config to get the JSON config for your client.

Note: This requires having idalib activated globally and uv installed:

# windows
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"
# macos
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"
# linux
uv run "/path/to/idapro-9.3/idalib/python/py-activate-idalib.py"

Related MCP server: IDAssistMCP

Installation (Claude Code)

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

Installation (Codex)

To install the latest IDA Pro MCP in Codex:

codex plugin marketplace add mrexodia/codex-marketplace
codex plugin remove ida-pro-mcp@mrexodia
codex plugin add ida-pro-mcp@mrexodia

Installation (Kimi Code)

To install the latest IDA Pro MCP in Kimi Code, run this slash command in the chat:

/plugins install https://github.com/mrexodia/ida-pro-mcp/tree/main
/reload

This installs the idalib MCP server and the idapython skill. Plugins are copied to $KIMI_CODE_HOME/plugins/managed/, so uv must be on your PATH. The first session after installing is slower, because uv resolves the dependencies before the server responds.

Installation (GUI)

Note: the MCP plugin is no longer recommended and will eventually be deprecated. Use idalib-mcp instead.

If you want to configure the MCP server manually from the IDA GUI:

pip uninstall ida-pro-mcp
pip install https://github.com/mrexodia/ida-pro-mcp/archive/refs/heads/main.zip

Configure the MCP servers and install the IDA Plugin:

ida-pro-mcp --install

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.

Large databases and repeated calls

Use func_scan for incremental function discovery on large binaries. Follow next_addr immediately; no cooldown or sleep is required between pages. Its page and scan limits bound work per request, not the total database size. Use func_query when you need global sorting or type filters.

Use decompile_batch(addrs=["main", "0x401000"], count=5) to retrieve several functions in one request. Pass the same address list and the returned next_offset as offset to resume. Each target has its own error result, so an invalid address does not prevent later targets from being processed. Address markers and referenced-symbol extraction are optional and disabled by default to reduce output and analysis work. Pages attempt at most 20 functions, with a deadline check between functions; a single slow native decompilation can still time out. Cancellation is propagated instead of being reported as an ordinary per-function failure.

When any tool's result exceeds the output limit, call output_read(output_id="<id from _meta.ida_mcp>"). Follow next_offset with the same ID to read the complete JSON in chunks. Concatenate the text fields before parsing; individual chunks need not be valid JSON. This uses the cached result without repeating analysis or accessing a download URL. Reads do not require IDA's main thread and have no cooldown. The cache keeps the latest 100 oversized results and their serialized JSON; entries are lost on eviction or restart. It is local to the producing IDA instance.

The GUI proxy now waits up to 300 seconds by default instead of 30. Set IDA_MCP_PROXY_TIMEOUT_SEC in the proxy process environment to another number of seconds, or 0 for no socket deadline. This applies to tool requests and output downloads. Invalid, negative, and non-finite values use the default.

Other deadlines are independent: IDA_MCP_TOOL_TIMEOUT_SEC controls the default IDA tool budget (individual tool decorators can override it), while IDA_MCP_WORKER_CALL_TIMEOUT and IDA_MCP_OPEN_TIMEOUT control headless worker call/open waits. Client deadlines may also apply. Disabling a proxy deadline does not disable these other deadlines or make IDA calls concurrent. IDA operations remain serialized on its main thread. These tools operate on loaded binaries/IDBs, not source repository trees.

Prompt Engineering

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:

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:

- Inspect the decompilation and add comments with your findings
- Rename variables to more sensible names
- Change the variable and argument types if necessary (especially pointer and array types)
- Change function names to be more descriptive
- If more details are necessary, disassemble the function and add comments with your findings
- NEVER convert number bases yourself. Use the `int_convert` MCP tool if needed!
- Do not attempt brute forcing, derive any solutions purely from the disassembly and simple python scripts
- Create a report.md with your findings and steps taken at the end
- When you find a solution, prompt to user for feedback with the password you found

This prompt was just the first experiment, please share if you found ways to improve the output!

Another prompt by @can1357:

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.

Use the following systematic methodology:

1. **Decompilation Analysis**
   - Thoroughly inspect the decompiler output
   - Add detailed comments documenting your findings
   - Focus on understanding the actual functionality and purpose of each component (do not rely on old, incorrect comments)

2. **Improve Readability in the Database**
   - Rename variables to sensible, descriptive names
   - Correct variable and argument types where necessary (especially pointers and array types)
   - Update function names to be descriptive of their actual purpose

3. **Deep Dive When Needed**
   - If more details are necessary, examine the disassembly and add comments with findings
   - Document any low-level behaviors that aren't clear from the decompilation alone
   - Use sub-agents to perform detailed analysis

4. **Important Constraints**
   - NEVER convert number bases yourself - use the int_convert MCP tool if needed
   - Use MCP tools to retrieve information as necessary
   - Derive all conclusions from actual analysis, not assumptions

5. **Documentation**
   - Produce comprehensive RE/*.md files with your findings
   - Document the steps taken and methodology used
   - When asked by the user, ensure accuracy over previous analysis file
   - Organize findings in a way that serves the project goals outlined in AGENTS.md or CLAUDE.md

Live stream discussing prompting and showing some real-world malware analysis:

Tips for Enhancing LLM Accuracy

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 for certain operations.

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:

• String encryption

• Import hashing

• Control flow flattening

• Code encryption

• Anti-decompilation tricks

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.

Transports & Headless MCP

You can run an SSE server to connect to the user interface like this:

uv run ida-pro-mcp --transport http://127.0.0.1:8744/sse

After installing idalib you can also run a headless MCP server. You can start with an initial binary:

uv run idalib-mcp --host 127.0.0.1 --port 8745 path/to/executable

Or start without a binary and open arbitrary files later with idb_open(...):

uv run idalib-mcp --host 127.0.0.1 --port 8745

For stdio-based clients, use:

uv run idalib-mcp --stdio

Database workers are persistent: each one runs as a detached process that outlives the supervisor that spawned it. When a new supervisor (over stdio or HTTP) calls idb_open for a binary that is already open under a worker on this host, the supervisor adopts that worker transparently — there is no separate "shared" mode to enable. Workers self-exit when no request has hit them for an idle interval.

Note: The idalib feature was contributed by Willi Ballenthin.

Headless idalib Session Model

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.

idb_open picks the backend via its mode parameter:

• prefer_headless (default): spawn an idalib worker (or adopt one that already has the file open).

• force_headless: same, but never adopt a running GUI even if one has the file.

• prefer_gui: adopt a running GUI for the file; otherwise spawn an idalib worker.

• force_gui: adopt a running GUI for the file; otherwise launch a new IDA GUI process.

Every tool call must carry an explicit database argument. There is no implicit "current database" — callers name the session they want to operate on.

uv run idalib-mcp --stdio --max-workers 4

Typical flow:

idb_open("/path/to/binary_a.exe", preferred_session_id="binary_a")
idb_open("/path/to/library.dll", preferred_session_id="library")

decompile("main", database="binary_a")
xrefs_to("ImportantExport", database="library")

database must be the session ID returned by idb_open (or shown in idb_list); filenames and paths are not accepted.

Management tools

• 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.

• 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.

• 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.

• 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.

• Per-database health: call server_health(database=<id>) (forwarded). idb_list() reports is_active from the supervisor's TCP/RPC probe.

Worker controls:

• --max-workers N: maximum simultaneous database workers (0 = unlimited, default 4).

• IDA_MCP_MAX_WORKERS: environment default for --max-workers.

The bundled Codex plugin forwards the runtime's IDA_MCP_* configuration variables from the Codex host environment:

• Capacity and lifecycle: IDA_MCP_MAX_WORKERS, IDA_MCP_OPEN_TIMEOUT, IDA_MCP_WEDGED_GRACE_SEC, IDA_MCP_WORKER_CALL_TIMEOUT.

• Health probes: IDA_MCP_HEALTH_TCP_TIMEOUT, IDA_MCP_HEALTH_RPC_TIMEOUT, IDA_MCP_HEALTH_RETRIES, IDA_MCP_HEALTH_RETRY_BACKOFF.

• Worker behavior: IDA_MCP_TOOL_TIMEOUT_SEC, IDA_MCP_ANALYSIS_PROMPT, IDA_MCP_URL.

• Request logging: IDA_MCP_LOG_REQUESTS, IDA_MCP_LOG_SKIP_METHODS.

MCP Resources

Resources represent browsable state (read-only data) following MCP's philosophy.

Core IDB State:

• ida://idb/metadata - IDB file info (path, arch, base, size, hashes)

• ida://idb/segments - Memory segments with permissions

• ida://idb/entrypoints - Entry points (main, TLS callbacks, etc.)

UI State:

• ida://cursor - Current cursor position and function

• ida://selection - Current selection range

Type Information:

• ida://types - All local types

• ida://structs - All structures/unions

• ida://struct/{name} - Structure definition with fields

Lookups:

• ida://import/{name} - Import details by name

• ida://export/{name} - Export details by name

• ida://xrefs/from/{addr} - Cross-references from address

Core Functions

• lookup_funcs(queries): Get function(s) by address or name (auto-detects, accepts list or comma-separated string).

• int_convert(inputs): Convert numbers to different formats (decimal, hex, bytes, ASCII, binary).

• list_funcs(queries): List functions (paginated, filtered).

• func_scan(start="0x0", count=100, scan_limit=10000, name_contains="", min_size=0): Stream functions in address order for large IDBs. Pass the returned next_addr as start with the same filters until it is null. Empty pages can still have a continuation. Each call examines at most scan_limit functions and returns at most count matches without building the entire function list. name_contains is a case-insensitive literal substring; size is the function's address span. Pages reflect the current IDB, so avoid changing function boundaries while scanning.

• list_globals(queries): List global variables (paginated, filtered).

• imports(offset, count): List all imported symbols with module names (paginated).

• decompile(addr): Decompile function at the given address.

• disasm(addr): Disassemble function with full details (arguments, stack frame, etc).

• xrefs_to(addrs): Get all cross-references to address(es).

• xrefs_to_field(queries): Get cross-references to specific struct field(s).

• callees(addrs): Get functions called by function(s) at address(es).

Modification Operations

• add_bookmark(addr, name, prefix): Add or replace the IDA bookmark at an address; set prefix="" for no prefix.

• set_comments(items): Set comments at address(es) in both disassembly and decompiler views.

• patch_asm(items): Patch assembly instructions at address(es).

• declare_type(decls): Declare C type(s) in the local type library.

• define_func(items): Define function(s) at address(es). Optionally specify end for explicit bounds.

• define_code(items): Convert bytes to code instruction(s) at address(es).

• undefine(items): Undefine item(s) at address(es), converting back to raw bytes. Optionally specify end or size.

Memory Reading Operations

• get_bytes(addrs): Read raw bytes at address(es).

• get_int(queries): Read integer values using ty (i8/u64/i16le/i16be/etc).

• get_string(addrs): Read null-terminated string(s).

• get_global_value(queries): Read global variable value(s) by address or name (auto-detects, compile-time values).

Stack Frame Operations

• stack_frame(addrs): Get stack frame variables for function(s).

• declare_stack(items): Create stack variable(s) at specified offset(s).

• delete_stack(items): Delete stack variable(s) by name.

Structure Operations

• read_struct(queries): Read structure field values at specific address(es).

• search_structs(filter): Search structures by name pattern.

Debugger Operations (Extension)

Debugger tools are hidden by default. Enable with ?ext=dbg query parameter:

http://127.0.0.1:13337/mcp?ext=dbg

Control:

• dbg_start(): Start debugger process.

• dbg_exit(): Exit debugger process.

• dbg_continue(): Continue execution.

• dbg_run_to(addr): Run to address.

• dbg_step_into(): Step into instruction.

• dbg_step_over(): Step over instruction.

Breakpoints:

• dbg_bps(): List all breakpoints.

• dbg_add_bp(addrs): Add breakpoint(s).

• dbg_delete_bp(addrs): Delete breakpoint(s).

• dbg_toggle_bp(items): Enable/disable breakpoint(s).

Registers:

• dbg_regs(): All registers, current thread.

• dbg_regs_all(): All registers, all threads.

• dbg_regs_remote(tids): All registers, specific thread(s).

• dbg_gpregs(): GP registers, current thread.

• dbg_gpregs_remote(tids): GP registers, specific thread(s).

• dbg_regs_named(names): Named registers, current thread.

• dbg_regs_named_remote(tid, names): Named registers, specific thread.

Stack & Memory:

• dbg_stacktrace(): Call stack with module/symbol info.

• dbg_read(regions): Read memory from debugged process.

• dbg_write(regions): Write memory to debugged process.

Advanced Analysis Operations

• py_eval(code): Execute arbitrary Python code in IDA context (returns dict with result/stdout/stderr, supports Jupyter-style evaluation).

• analyze_funcs(addrs): Comprehensive function analysis (decompilation, assembly, xrefs, callees, callers, strings, constants, basic blocks).

Emulation

• emulate(start, end="", regs=None, write=None, read=None, ...): Run x86-64 code from the IDB in the Unicorn engine without launching the process. Every segment is mapped at its real address, so intra-binary calls, jump tables and data references resolve automatically; unresolved external calls are skipped (reported in calls) and stray memory accesses lazily map zero pages, so self-contained routines run to completion. Set inputs via regs/write, read outputs from the returned registers or read memory dumps (a read address may be @rax etc. to dereference a final register). Great for executing string/config decryptors, hashing stubs, and opaque predicates instead of reasoning about them by hand. Requires the optional unicorn dependency in IDA's Python (pip install unicorn).

Triage

• find_crypto(): Scan the database for well-known cryptographic constants (AES S-boxes, SHA-256/512, MD5/SHA-1 tables and IVs, CRC32 table, base64 alphabets, ChaCha/Salsa sigma). Returns each hit with address and segment. Pairs well with emulate (find the crypto, then run it).

• detect_capabilities(): Fingerprint behaviour from imported APIs and strings against a capa-style ruleset. Returns matched capabilities (process injection, persistence, anti-debugging, keylogging, C2, crypto, etc.), each with a MITRE ATT&CK technique id and the evidence that fired it. A triage layer on top of survey_binary.

Pattern Matching & Search

• list_strings(filter="", min_length=4, segment="", with_xrefs=False, offset=0, count=200): Enumerate strings (ASCII + UTF-16) with regex/segment/length filtering and pagination. With with_xrefs, each string carries the code locations that reference it and their function names, so you can jump straight from an interesting string to the routine that uses it.

• find_regex(queries): Search strings with case-insensitive regex (paginated).

• find_bytes(patterns, limit=1000, offset=0): Find byte pattern(s) in binary (e.g., "48 8B ?? ??"). Max limit: 10000.

• find_insns(sequences, limit=1000, offset=0): Find instruction sequence(s) in code. Max limit: 10000.

• find(type, targets, limit=1000, offset=0): Advanced search (immediate values, strings, data/code references). Max limit: 10000.

Control Flow Analysis

• basic_blocks(addrs): Get basic blocks with successors and predecessors.

Type Operations

• set_type(edits): Apply type(s) to functions, globals, locals, or stack variables.

• infer_types(addrs): Infer types at address(es) using Hex-Rays or heuristics.

Export Operations

• export_funcs(addrs, format): Export function(s) in specified format (json, c_header, or prototypes).

• export_patched_binary(output_path, overwrite=False): Write the database's applied byte patches (from patch/patch_asm) back out to a runnable binary on disk, overlaying each patched byte at its file offset. The step that turns IDB edits into a patched executable.

Graph Operations

• callgraph(roots, max_depth): Build call graph from root function(s) with configurable depth.

Batch Operations

• rename(batch): Unified batch rename operation for functions, globals, locals, and stack variables (accepts dict with optional func, data, local, stack keys).

• patch(patches): Patch multiple byte sequences at once.

• put_int(items): Write integer values using ty (i8/u64/i16le/i16be/etc).

Key Features:

• Type-safe API: All functions use strongly-typed parameters with TypedDict schemas for better IDE support and LLM structured outputs

• Batch-first design: Most operations accept both single items and lists

• Consistent error handling: All batch operations return [{..., error: null|string}, ...]

• Cursor-based pagination: Search functions return cursor: {next: offset} or {done: true} (default limit: 1000, enforced max: 10000 to prevent token overflow)

• Performance: Strings are cached with MD5-based invalidation to avoid repeated build_strlist calls in large projects

Development

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):

https://github.com/user-attachments/assets/951de823-88ea-4235-adcb-9257e316ae64

To test the MCP server itself:

npx -y @modelcontextprotocol/inspector

This will open a web interface at http://localhost:5173 and allow you to interact with the MCP tools for testing.

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 you can run the following command:

uv run ida-pro-mcp --install

Generate the changelog of direct commits to main:

git log --first-parent --no-merges 1.2.0..main "--pretty=- %s"