ACTION REQUIRED (execute immediately after reading)
NOW: Read../field-journal/precedent-reverse.md— confirm that this skill's operations are authorized routine operationsNOW: Confirm whether the current task falls within the applicable scope of this skillNEXT: Read../tool-index.md, verify tool availability and actual pathsNEXT: When tools are missing, call bootstrap; do not guess pathsACT: Enter the first step of the "workflow" and execute it; do not stop in the confirmation state
Known issues and reflections (required reading)
Pitfalls encountered
-
idb_open(old nameidalib_open) do not directly rely on partial code AI client MCP calls- The MCP client of partial code AI clients has a BUG in output schema validation for open-type tools
- Error:
Structured content does not match the tool's output schema - Solution: Use
scripts/open.ps1scripts to call directly via HTTP API, bypassing the MCP validation layer - The current ida-pro-mcp 2.x tool name is
idb_open/idb_list/idb_save(no longeridalib_*) - After the file is opened it returns
session_id(database); subsequent tool calls need to carry this session
-
C:\Windows\System32\file cannot be opened due to insufficient permissions- idalib cannot directly read files in the System32 directory
- Solution:
open.ps1automatically detects and copies to the临时目录directory before opening
-
Starting the server command blocks the conversation
idalib-mcpAfter startup, it continuously outputs INFO logs to the console- Solution: Use
scripts/start.ps1(-WindowStyle Hiddenbackground silent startup) - The script waits for the service to be ready and then exits automatically, without blocking the conversation
-
MCP server names cannot use hyphens
- Previously
ida-pro-mcpwas used as the server name, which may cause tool registration issues - Current configuration: server name
idapro, tool prefixidapro_*
- Previously
-
Remote HTTP vs Local Stdio
type:"local"(stdio) mode:idalib_openalso has schema validation issuestype:"remote"(HTTP) mode: you can first use a script to open the file directly, then use MCP tools- Current solution: Remote HTTP mode
-
PR #389 fixed some schema issues
- Author mrexodia merged the fix via PR #389 after issue #388
- Fixed the structuredContent schema in HTTP mode, but validation issues remain on the partial code AI client side
- Installed the latest
mainbranch version
-
idalib timeout leaves orphan worker process lock files
- After the first
open.ps1timeout, idalib's python worker subprocess may become orphaned, holding onto.id0/.id1/.namand not letting go - Any subsequent tool or manual drag into IDA GUI will report "insufficient permissions"
- Prohibited
taskkill /F /Tkill the process tree—/Twill also kill the GUIida.exesubprocess - Solution:
start.ps1Only when no one is listening on the port, ortools/listreturns quickly but lackspy_eval(old supervisor), replace the managed supervisor; if the RPC times out and 13337 is still listening, treat it as busy and do not kill it. When opening the database,open.ps1writesopening.lock, the watchdog must not-Force - Deadlock exception:
tools/listContinuous failure for more than 3 minutes(based on the last-healthy timestamp, not the process creation time), and there is no in-flightopening.lock, and it is not the GUI holding the port, only then-Forcereplace the supervisor, still do not killida.exe - Fallback:
open.ps1When it detects that the old database is locked, automatically copy it to Temp and add a GUID prefix
- After the first
-
Opening with automatic analysis looks like it is stuck
idalib_open(run_auto_analysis=true)may not respond for a long time, but the backend is actually still opening and analyzing- Previously, what the user saw was “PowerShell keeps producing no output,” which is easily mistaken for the script being stuck
- Current solution:
open.ps1added-TimeoutSeconds, and changed it to background request + foreground polling + periodic progress output - When polling detects that the session is ready, it returns early with
OK:文件名:session_id, and on timeout returnsERR:open_timeout_xxs
-
HTTP MCP silently exits after login
- Cursor/Claude’s
type: httpwill not start the process on its behalf; the old scheduled task only runs once at login pythonwhas no console, and when it crashes the Application log is also empty- Solution:
start.ps1If healthy by default, reuse it;watchdog.ps1patrol every minute; logs are in%LOCALAPPDATA%\reverse-skill\ida-mcp\ - Installation:
scripts/install-autostart.ps1. If the port is not up yet when the HTTP client starts, you still need to manually refresh once in the MCP panel
- Cursor/Claude’s
-
Streamable HTTP GET
/mcpwill get the single-threaded supervisor stuck
- Some HTTP MCP clients will send a long-lived GET (SSE) to
/mcp. stockidalib_supervisorusesbackground=False’sHTTPServer, and handles only one request at a time - Result:
tools/listtimes out, and the client marksidaproas error - Solution:
run-supervisor.pyReplace HTTP withThreadingHTTPServerand accept GET/mcp; if the patch fails, skip it and still start the supervisor. When stuck, usescripts/recover.ps1(immediately-Force)
Workflow principles
| Step | What to do | What to use |
|---|---|---|
| 1 | Make sure the HTTP server is running | scripts/start.ps1(no arguments) |
| 2 | Open the target binary file | scripts/open.ps1 -Path "xxx.exe" |
| 3 | Use the MCP analysis tools | Call directly idapro_* / HTTP tools (about 65, depending on version) |
| 4 | Analysis complete | Tools are automatically available |
Script resources
start.ps1 — Start the MCP HTTP server
Path:scripts/start.ps1
- Automatically resolve
IDADIR(environment variable / portable desktop path / common installation path) - Prefer IDA’s built-in
Python314\python.exe -m ida_pro_mcp.idalib_supervisor - By default, probe first
http://127.0.0.1:13337/mcp, and if healthy outputOK:<n>:reuseand exit - 13337 is listening but
tools/listtimes out →WARN:busy/OK:busy:reuse,do not kill(cannot respond when opening the database or when the GUI is occupying it) tools/listContinuous failure for more than 3 minutes(last-healthy timestamp) and noopening.lock→ considered a deadlock, outputINFO:deadlockand-Forcereplace supervisor. In-progressidb_openand GUI will not take this path- Only when no one is listening on the port, missing
py_eval, or the aforementioned deadlock, is the managed supervisor replaced;never killida.exe, do not usetaskkill /T - When the GUI occupies 13337, output
WARN:gui_busyand exit, without starting another supervisor - On success, output
OK:<工具数>(currently about 66), on failure outputERR:timeout - supervisor log:
%LOCALAPPDATA%\reverse-skill\ida-mcp\supervisor.log - The server runs in the background without blocking the conversation
How to invoke:
powershell -File "<skill-root>\ida-reverse\scripts\start.ps1"
watchdog.ps1 / recover.ps1 / install-autostart.ps1 — keep-alive
watchdog.ps1: probe 13337; healthy reuse (and refresh last-healthy); GUI /open.ps1open database lock / last-healthy not yet 3 minutes busy → reuse; onlytools/listafter more than 3 minutes of consecutive failures dostart.ps1 -Forcerecover.ps1: immediatelystart.ps1 -Force(without killingida.exe). Use this when the HTTP client marksidaproas errorinstall-autostart.ps1: register scheduled taskreverse-skill-ida-mcp(logon + every minute)- Log:
%LOCALAPPDATA%\reverse-skill\ida-mcp\watchdog.log
open.ps1 — open a binary file
Path:scripts/open.ps1
- Call directly via the HTTP API
idb_open, bypassing MCP schema validation - Automatically detect the System32 path and copy it to a temporary directory
- Automatically clean up old database files with the same name (
.id0/.id1/.nam/.til/.i64) - When the old database is locked, automatically degrade: copy to Temp with a GUID prefix and open it, without reporting an error
- Execute the open request in the background to avoid the script becoming unresponsive due to a long synchronous wait
- Support
-TimeoutSeconds, return after timeoutERR:open_timeout_xxs, will not hang indefinitely - Output once every 10 seconds
INFO:opening:已用时/超时秒数, to help determine that analysis is still in progress - On success, output
OK:文件名:session_id, when degraded add(temp copy)marker - On failure, automatically retry using the Temp copy
How to invoke:
powershell -File "<skill-root>\ida-reverse\scripts\open.ps1" -Path "C:\path\to\file.exe"
Optional parameters:
# 指定 SessionId
powershell -File "scripts\open.ps1" -Path "file.exe" -SessionId "my_session"
# 跳过自动分析(大文件推荐)
powershell -File "scripts\open.ps1" -Path "large.exe" -NoAutoAnalysis
# 设置超时,避免带自动分析时长时间无返回
powershell -File "scripts\open.ps1" -Path "file.exe" -TimeoutSeconds 600
Output conventions:
# 分析进行中(每 10 秒输出一次)
INFO:opening:11/600s
# 成功打开
OK:sample.exe:abcd1234
# 成功打开,但因锁文件降级到 Temp 副本
OK:1234abcd-sample.exe:abcd1234 (temp copy)
# 达到超时上限
ERR:open_timeout_600s
Measured notes:
Snipaste.exewith automatic analysis actually takes about324sbefore returning success; this is "analysis takes a long time" rather than "script deadlock"- Therefore, when encountering GUI programs or more complex samples, it is recommended to first explicitly set
-TimeoutSeconds 600
Core tool list
Overview analysis (first step)
idapro_survey_binary(detail_level="minimal")— quick overview: function count, strings, segments, entry point, import categories (crypto/network/file IO)idapro_list_funcs(queries)— list functions (paged, filter by name)idapro_list_globals(queries)— list global variablesidapro_entity_query(kind, filter)— unified query: functions/globals/imports/strings/names
Decompilation and disassembly
idapro_decompile(addr)— decompile to pseudocodeidapro_disasm(addr, max_instructions=N)— disassembleidapro_analyze_function(addr, include_asm=false)— comprehensive analysis (pseudocode + strings + constants + callers + callees + blocks)idapro_func_profile(queries)— function summary metrics
Cross-references and data flow
idapro_xrefs_to(addrs)— find who references the target addressidapro_xref_query(addr, direction)— advanced xref query (direction/type filtering)idapro_callees(addrs)— subfunction listidapro_callgraph(roots, max_depth)— call graphidapro_trace_data_flow(addr, direction, max_depth)— data flow tracing (forward/backward)
Search
idapro_find_regex(pattern, limit)— Regex string searchidapro_search_text(pattern)— Search text in the disassembly listingidapro_find_bytes(patterns, limit)— Byte pattern search (supports ?? wildcards)idapro_find(type, targets)— Advanced search (immediates/strings/references)
Memory and Data
idapro_get_bytes(addrs)— Read raw bytesidapro_get_string(addrs)— Read stringidapro_get_int(queries)— Read integer valueidapro_get_global_value(queries)— Read global variable valueidapro_read_struct(queries)— Read struct field valueidapro_search_structs(filter)— Search structs
Modification Operations
idapro_set_comments(items)— Add comment (bidirectionally synced between disassembly and decompilation)idapro_append_comments(items)— Append commentidapro_rename(batch)— Batch rename (functions/globals/locals/stack variables)idapro_patch_asm(items)— Patch assembly instructionsidapro_patch(patches)— Patch bytesidapro_define_func(items)— Define functionidapro_undefine(items)— Undefineidapro_define_code(items)— Convert bytes to code
Type System
idapro_declare_type(decls)— Declare C struct/union/enumidapro_set_type(edits)— Apply type to function/global/localidapro_infer_types(addrs)— Infer typeidapro_type_query(queries)— Query declared typesidapro_type_inspect(queries)— View type details
Stack Frame
idapro_stack_frame(addrs)— View stack frame variablesidapro_declare_stack(items)— Declare stack variableidapro_delete_stack(items)— Delete stack variable
Signatures
idapro_make_signature(addrs)— Generate a unique byte signature for an addressidapro_make_signature_for_function(addrs)— Generate a signature for a functionidapro_find_xref_signatures(addrs)— Generate a signature for code that references an address
Debugger (requires ?ext=dbg)
idapro_open_file(file_path)— Open file in a GUI IDA instance- Debugger tools are hidden by default; they can be enabled via the URL parameter
?ext=dbgEnable
Session Management (ida-pro-mcp 2.x)
idapro_idb_open/ HTTPidb_open— ⚠️ Recommended to useopen.ps1to openidapro_idb_list/ HTTPidb_list— List all sessionsidapro_idb_save/ HTTPidb_save— Save database- Most analysis tools require the
database=<session_id>parameter (the session output by open.ps1)
Other
idapro_int_convert(inputs)— Base conversion (you must use this, don't compute bases yourself!)idapro_export_funcs(addrs, format)— Export functions (json/c_header/prototypes)idapro_py_eval(code)— Execute Python in the IDA contextidapro_server_health()— Server health checkidapro_server_warmup()— Warm up subsystems (string cache, Hex-Rays, etc.)
Complete Reverse Engineering Analysis Workflow
Step 1: Start the server
Path A — Headless idalib (requires a valid license)
powershell -File "scripts/start.ps1"
Output OK:<工具数>(currently about 65) indicates ready.
Path B — GUI + plugin (when the idalib license fails or interactive analysis is needed)
powershell -File "scripts/start-gui.ps1" -Path "C:\目标.exe"
Or double-click the portable Launch-IDA-Pro.cmdand open the sample in IDA.
After confirming that the Output window shows [MCP] ... port=13337 the MCP tools are available.
For general integration steps see LOCAL-SETUP.md。
Step 2: Open the file
Headless:
powershell -File "scripts/open.ps1" -Path "C:\目标.exe" -TimeoutSeconds 600
Output OK:文件名:session_id indicates success (followed by (temp copy) indicates automatic fallback to a temporary copy).
If ERR:idalib_license:...appears, switch to Path B (GUI mode) and do not repeatedly retry open.ps1.
GUI mode: simply open the sample directly in IDA; open.ps1 is not needed.
Step 3: Global overview (including the import table hard gate)
idapro_survey_binary(detail_level="minimal")
Focus on:
- architecture (x86/x64/ARM)
- Entry points (main/WinMain/DllMain)
- Interesting strings (URLs, paths, error messages)
- Import classification (MUST): encryption functions / network APIs / file operations / process injection / registry — must be recorded as Evidence (suggested id:
E-imports), availableidapro_entity_query(kind="imports")or the imports section in the survey output - DLL/SYS: export table in parallel with import table (Evidence
E-exports) - .NET: when there is no traditional IAT, use module/metadata/managed-reference summaries as equivalent anchors and write them into the E-imports semantic slot
- Clean import table: note dynamic-loading suspicion and drive dynamic API breakpoint verification
- Hot functions (functions with high xref counts are usually key logic)
Hard gate: before the imports view/classification summary (or a legitimate equivalent anchor) is written into Evidence, MUST NOT proceed to Step 4 deep-dive conclusions, MUST NOT claim survey is complete. If the import table is empty or the query fails, still MUST record the failure symptom. If packed IAT repair fails, MUST record E-iat-repair-fail and switch to dynamic debugging to capture APIs; static grinding is forbidden. When the user requests redoing the import table/IAT check, MUST redo the named steps (when blocked, feasibility gate: explain + confirm; if forced, mark quality=unreadable); switching to unrelated steps is forbidden.
Step 4: Deep dive into key functions
idapro_analyze_function(addr="关键函数名")
Or:
idapro_decompile(addr="函数名")
idapro_disasm(addr="函数名", max_instructions=50)
Step 5: Data flow and cross-references
idapro_xrefs_to(addrs="关键地址/字符串")
idapro_callgraph(roots=["关键函数"], max_depth=3)
idapro_trace_data_flow(addr="关键地址", direction="backward", max_depth=5)
Step 6: Record and optimize
idapro_set_comments(items=[{"addr": "0x140001000", "comment": "你的理解"}])
idapro_rename(batch={"func": [{"addr": "函数地址", "name": "有意义的名字"}]})
Step 7: Output report
After analysis is complete, generate report.md to record findings and steps.
Prompt engineering guidelines
- Do not calculate bases manually — whenever you need to convert numbers, use
idapro_int_convert - Survey first, then deep dive — look at the overview first, then perform targeted analysis
- Continuously add comments and rename — keep updating function names and variable names during analysis to improve the accuracy of subsequent analysis
- Track cross-references — when you find interesting data/strings, use
xrefs_toto see who references it - When encountering obfuscated code — first perform preprocessing such as string decryption, import hash removal, and control-flow flattening removal
- C++ STL code — after identifying library functions with FLIRT/Lumina, then analyze the business logic
- Do not brute force — analysis should derive solutions from the disassembly, using simple Python to assist calculations
- When encountering "No database bound" — no binary file has been opened yet; first execute
open.ps1 - When encountering "Failed to open database" — possibly an old database file is locked,
open.ps1will automatically fall back to a Temp copy (output contains the(temp copy)marker) - When opening the GUI/complex samples with auto-analysis — by default add
-TimeoutSeconds 600, do not misjudge a longINFO:opening:...as the script being stuck
Routing context
Upstream entry: skills/SKILL.md(master control),routing.md
Upstream alternate: radare2/(if you do not want to open IDA, you can first do quick reconnaissance with r2)
Downstream exit:
- Needs Frida dynamic verification →
reverse-engineering/tools-dynamic.md - Needs symbolic execution/angr →
reverse-engineering/tools-dynamic.md - Needs general reverse-engineering methodology →
reverse-engineering/SKILL.md
Sibling related modules: radare2/(Alternative when IDA is unavailable)
On-Demand Bootstrap
This skill's entry script is already integrated with the unified bootstrap system.
Automation capability boundaries
| Tool | Can be installed automatically | Installation method | Description |
|---|---|---|---|
| idalib-mcp | ✓ | pip install (from GitHub) | start.ps1 automatically installed when missing |
| IDA Pro itself | ✗ | Commercial software, requires manual installation | Set the IDADIR environment variable to point to the installation directory |
Installation steps (verified)
# 1. 设置 IDA 路径(替换为你的实际 IDA 安装目录)
setx IDADIR "<你的IDA安装目录>"
# 2. 从 GitHub 安装 ida-pro-mcp(PyPI 上的 ida-mcp 是另一个项目,不要装错!)
pip install git+https://github.com/mrexodia/ida-pro-mcp.git
# 3. 安装 IDA 插件(选择 Streamable HTTP + Global + 全选客户端)
ida-pro-mcp --install
# 4. 重启 IDA Pro,打开目标文件
# 插件自动监听 127.0.0.1:13337
# 5. 验证
ida-pro-mcp --config
⚠️ Note: the
ida-mcppackage on PyPI (author jtsylve) is a different project, not the one we need. It must be installed from GitHubmrexodia/ida-pro-mcp。
Bootstrap trigger point
scripts/start.ps1: whenidalib-mcpis missing, automatically callbootstrap-reverse.ps1- MCP registration: bootstrap will automatically write
idaprointo the Claude MCP configuration
Prerequisites
- IDA Pro is installed and the
IDADIRenvironment variable is set (or the default path in the script is correct) - It is recommended to use the
ida-pro-mcpin IDA's bundled Python314 (already included in the portable version) - Common local configuration:
- User env
IDADIR→ IDA installation directory (includingida.exe) - Optional
~\Tools\bin\idalib-mcp.cmd/ida-pro-mcp.cmdwrapper - For the client MCP server name, keep only
idapro→http://127.0.0.1:13337/mcp
- User env
Task completion self-check (MUST pass before claiming completion)
- Did I execute every step in the workflow (rather than just reading it)?
- Have survey/imports been written into Evidence (E-imports or equivalent)? Do DLL/SYS include E-exports? If IAT fails, is E-iat-repair-fail recorded?
- If the user asks to redo the import table/IAT, was the same step redone?
- Did I base this on
tool-indexand use real tool paths? - Did I produce reproducible evidence (commands/scripts/screenshots/reports)?
- Did I complete and write back the Checklist items required by RULES?