IDA Assistant

English | 简体中文

把 IDA Pro 变成一个能长期干活、又能被多个 AI agent 同时安全使用的分析服务。

它不需要你打开 IDA 图形界面，也不需要你守着它。你让 agent 去分析一个二进制，然后可以关掉 对话、切换项目、甚至重启客户端——IDB 照样会被建好。回头看结果就行。

为什么会有这个项目

直接给 agent 接 IDA 时，每个人都会撞上同一堵墙：分析一个稍大的二进制要几分钟到几小时，而 MCP 请求和对话有超时。

常见的失败长这样：agent 调一次 open，客户端在 30 秒后超时；重试一次，于是 IDA 又被启动了 一遍；等你终于等到分析结束，对话上下文已经断了。更糟的是第一次失败重试时，两个 IDA 进程正 在抢同一个 IDB。

IDA Assistant 把「分析」和「提问」拆开：

• 分析是一个独立的后台作业，跑在脱离客户端的进程里，管它等你多久。客户端断开、scheduler 退出、请求超时，都不会杀掉它。

• 只有完整分析结束后，IDB 才会被发布。在那之前任何查询都会明确告诉你"还没好"，而不是 拿一个半成品数据库骗你。

• 多个 agent 可以同时用。谁先发起就谁负责建库，其他人复用；同一时刻只有一个进程能写同一 个 IDB。

Related MCP server: idalib-mcp-headless

前置条件

项目根目录必须在 Windows 文件系统上。从 WSL 里用时要走 /mnt/c/... 这类路径；/home/... 会被转成 \\wsl.localhost\...，那里的锁语义不满足要求，scheduler 会直接拒绝启动并告诉你原因。

本插件不包含、也不分发任何 Hex-Rays 或 IDA 代码。

快速开始

# 1. 把上游依赖装进独立环境
uv tool install ida-pro-mcp

# 2. 生成指向本机的 .mcp.json
pwsh -File scripts/install.ps1

install.ps1 会自动探测解释器、site-packages 和 IDA 目录，把模板里的占位符替换成真实路径。 如果探测不对，用环境变量覆盖：

生成的 .mcp.json 是本地文件，不进版本库：仓库里只有模板，所以个人路径不会进 git 历史。

接到客户端

stdio（单客户端，推荐）

生成好的 .mcp.json 直接给 Codex 用。其他客户端把等价的 command/args 填进去即可：

{
  "mcpServers": {
    "ida": {
      "command": "<pythonw.exe 路径>",
      "args": [
        "<仓库路径>\\scripts\\ida_lazy_mcp.py",
        "--transport", "stdio",
        "--agent", "my-agent",
        "--worker-command", "<python.exe 路径>",
        "--ida-dir", "C:\\Program Files\\IDA Professional 9.1",
        "--pythonpath", "<ida-pro-mcp 的 site-packages>"
      ]
    }
  }
}

HTTP（多客户端共享一个 scheduler）

pwsh -File scripts/start_http.ps1 -ProjectRoot D:\samples\app

对应配置见 config/codex-http.mcp.json 与 config/pi-http.mcp.json。

WSL / pi

config/pi-stdio.mcp.json 用 wslpath -w "$PWD" 把当前目录转成 Windows 路径，其余参数照常。 它使用 keep-alive，避免客户端空闲回收打断大 IDB 的保存。

怎么用

第一次调用只需要给一个路径：

ida/open(path="bin/app.exe")

它立刻返回，因为真正的分析在后台跑。接着：

ida/analysis_status()      # 纯读状态，不碰 IDA，繁忙时也秒回
ida/wait_for_analysis()    # 只在这次调用确实需要等待时才用

状态走完 launching → queued → analyzing → publishing → ready 之后，开始提问：

ida/metadata()
ida/functions(filter="license")
ida/imports()
ida/strings(filter="api")
ida/function(value="0x140001000")
ida/decompile(address="0x140001000")
ida/disassemble(address="0x140001000")
ida/xrefs(address="0x140001000", kind="callers")
ida/basic_blocks(address="0x140001000")
ida/inspect(kind="segments")
ida/search(query="4D 5A", kind="bytes")
ida/bytes(address="0x140001000", size=64)

之后不必再传 path 或 session：当前活跃分析是按 MCP 连接隔离的。

管理会话

ida/sessions()                    # 列出所有项目分析、worker、错误与配额
ida/current()                     # 当前连接在用哪个
ida/use(session="app")            # 切到一个已有分析（不会新建）
ida/rename_session(session="app", new_name="app-v2")
ida/close()                       # 关掉查询 worker，IDB 与后台作业保留
ida/logs(session="app", lines=200)# 事件、bootstrap、worker stderr 的尾部

取消分析

close 不会停后台作业——这是有意的。真要取消：

ida/abort(session="app", job_id="<从 analysis_status 取>", confirm=true)

带上 job_id 是为了避免一个迟到的取消请求误杀掉重试后的新作业。

编辑与 Python

连接默认是只读的。需要写入时显式开启对应能力：

ida/set_capabilities(edit=true)      # 允许注释、改名、改类型、打补丁
ida/set_capabilities(debug=true)     # 允许调试器操作
ida/set_capabilities(python=true)    # 允许不受限的 IDAPython

• edit / debug 每次调用仍要带 confirm=true。

• python 是完整的 IDAPython：能读写文件、发起网络请求、启动进程。只对可信样本和可信调用方开。

• 能力是按连接生效的，不会影响别人。

和「直接接 IDA MCP」的区别

工具一览

安全须知

• HTTP transport 没有任何认证，只绑定 127.0.0.1。不要改绑定地址，不要暴露到网络。

• 默认只读。python 能力等于把机器交给调用方，按最小权限开启。

• 不要用它分析不可信样本，也不要用于未授权软件。

兼容性

上游 ida-pro-mcp 没有稳定的公开接口。本插件要读它的注册表（rpc_registry.methods / .unsafe），并把里面的函数重新注册成 MCP 工具。

升级上游后如果出现下面这些症状，先怀疑兼容性：

最后一行无法自动发现：名字和参数都没变，但返回的东西意思变了。所以升级上游后，如果一个 查询的结果看着不对、且差异是相对旧版比较出来的，这是首要嫌疑。

排错

更多故障码与超时语义见 内部实现。

开发

uv sync
uv run python -m unittest discover -s tests -v
uv run --with ruff ruff check ida_assistant tests

不需要 IDA 就能跑的是 fake 测试（覆盖后台作业、发布门禁、原子保存、scheduler 重启、abort 与 worker 恢复）。真实 IDA 测试会在缺少安装时自动 skip：

$env:IDA_ASSISTANT_IDA_DIR = "C:\Program Files\IDA Professional 9.1"
$env:IDA_ASSISTANT_IDA_MCP_PATH = "$env:APPDATA\uv\tools\ida-pro-mcp\Lib\site-packages"
uv run python -m unittest discover -s tests -v

改代码前建议先读 docs/internals.md，那里解释了磁盘状态与锁的约束。

许可证

MIT，见 LICENSE。本项目不包含任何 Hex-Rays 或 IDA 代码；"IDA" 与 "Hex-Rays" 是 各自所有者的商标。