ida-mcp-rs

Headless IDA Pro MCP server for AI-powered reverse engineering.

## 前置条件 - IDA Pro 9.2+ 及有效许可证（推荐 9.3sp1） ## 入门指南 ### 安装 **macOS / Linux**（通过 [Homebrew](https://brew.sh)） ``` brew install blacktop/tap/ida-mcp # Latest (IDA 9.3/9.3sp1) brew install blacktop/tap/ida-mcp@9.2 # IDA 9.2 ``` **Windows**（通过 [Scoop](https://scoop.sh)） ``` scoop bucket add blacktop https://github.com/blacktop/scoop-bucket scoop install blacktop/ida-mcp ``` **macOS / Linux**（通过 [Nix](https://nixos.org)） ``` nix shell github:blacktop/nur#ida-mcp \ --extra-experimental-features 'nix-command flakes' ``` **Linux**（通过 [Snap](https://snapcraft.io/ida-mcp)） ``` sudo snap install ida-mcp sudo snap connect ida-mcp:dot-idapro # grant access to ~/.idapro (license) ``` **直接下载** — 从 [GitHub Releases](https://github.com/blacktop/ida-mcp-rs/releases) 获取适用于您平台的压缩包。 **从源码构建** 参阅 [docs/BUILDING.md](docs/BUILDING.md)。 ### 平台设置 #### macOS 在 `/Applications` 中的标准 IDA 安装会自动生效： ``` claude mcp add ida -- ida-mcp ``` 如果您看到 `Library not loaded: @rpath/libida.dylib`，请将 `DYLD_LIBRARY_PATH` 设置为您的 IDA 路径： ``` claude mcp add ida -e DYLD_LIBRARY_PATH='/path/to/IDA.app/Contents/MacOS' -- ida-mcp ``` 支持的路径（自动检测）： - `/Applications/IDA Professional 9.3.app/Contents/MacOS` - `/Applications/IDA Home 9.3.app/Contents/MacOS` - `/Applications/IDA Essential 9.3.app/Contents/MacOS` - `/Applications/IDA Professional 9.2.app/Contents/MacOS` #### Linux IDA 安装程序默认安装到 `~/ida-pro-9.3` — 启动脚本会自动检测此路径： ``` claude mcp add ida -- ida-mcp ``` 对于非默认安装位置，请设置 `IDADIR`： ``` claude mcp add ida -e IDADIR='/path/to/ida' -- ida-mcp ``` 解析顺序：`$IDADIR` → `~/ida-pro-9.3` → `/opt/ida-pro-9.3` 以及其他 RUNPATH 回退。 #### Windows **选项 A** — 将 `ida-mcp.exe` 安装到您的 IDA 目录中（最简单，无需设置环境变量）： ``` # 将二进制文件复制到 ida.dll / idalib.dll 旁边 copy ida-mcp.exe "C:\Program Files\IDA Professional 9.3\" claude mcp add ida -- "C:\Program Files\IDA Professional 9.3\ida-mcp.exe" ``` **选项 B** — 通过 [Scoop](https://scoop.sh) 安装（自动检测 IDA 并设置 `IDADIR`）： ``` scoop bucket add blacktop https://github.com/blacktop/scoop-bucket scoop install blacktop/ida-mcp claude mcp add ida -- ida-mcp ``` **选项 C** — 手动设置 `IDADIR`： ``` # 持久化（重启后仍有效） setx IDADIR "C:\Program Files\IDA Professional 9.3" # 然后重启你的终端 claude mcp add ida -- ida-mcp ``` Windows 要求在启动时能找到 `ida.dll` 和 `idalib.dll`。将 `ida-mcp.exe` 放在 IDA 目录中是最简单的方法。否则，必须将 IDA 目录添加到 `PATH` 中或通过 `IDADIR` 指定。 常见的 IDA 路径： - `C:\Program Files\IDA Professional 9.3` - `C:\Program Files\IDA Pro 9.3` - `C:\Program Files\IDA Home 9.3` ### 运行时要求 该二进制文件在运行时会链接到 IDA 的库。标准安装路径通过内置的 RPATH 自动检测。对于非标准路径： | 平台 | 库 | 回退配置 | |----------|---------|------------------------| | macOS | `libida.dylib` | `DYLD_LIBRARY_PATH` | | Linux | `libida.so` | `IDADIR`（启动脚本读取）或 `LD_LIBRARY_PATH` | | Windows | `ida.dll` | 将 exe 放在 IDA 目录中，设置 `IDADIR`，或将 IDA 目录添加到 `PATH` | ### 配置您的 AI 代理 #### [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) ``` claude mcp add ida -- ida-mcp ``` #### [Codex CLI](https://github.com/openai/codex) ``` codex mcp add ida -- ida-mcp ``` #### [Gemini CLI](https://github.com/google-gemini/gemini-cli) ``` gemini mcp add ida -- ida-mcp ``` #### [Cursor](https://cursor.com) 添加到 `.cursor/mcp.json`： ``` { "mcpServers": { "ida": { "command": "ida-mcp" } } } ``` ### 用法 配置完成后，您可以通过 AI 代理分析二进制文件： ``` # 打开一个二进制文件（快速返回 — 分析在后台单独运行） open_idb(path: "~/samples/malware") # 这些功能可立即使用，无需进行分析 list_functions(limit: 20) disasm_by_name(name: "main", count: 20) strings(limit: 10) # 对于大型二进制文件的 xrefs/decompile 操作，请在后台运行分析 analyze_funcs(background: true) # returns task_id task_status(task_id: "analyze-1") # poll progress # Decompile（需要 Hex-Rays + 已完成分析） decompile(address: "0x100000f00") # 探索更多工具 tool_catalog(query: "find callers") ``` #### `dyld_shared_cache` 分析 `open_dsc` 用于打开 Apple dyld_shared_cache 中的单个模块。首次使用时，它会在后台运行 `idat` 以创建 `.i64` 文件（这可能需要几分钟）。随后的打开过程将是瞬间完成的。 ``` # 从 DSC 中打开一个模块 open_dsc(path: "/path/to/dyld_shared_cache_arm64e", arch: "arm64e", module: "/usr/lib/libobjc.A.dylib") # 如果已启动后台任务，则轮询直到完成 task_status(task_id: "dsc-1") # 加载额外的 frameworks 以实现跨模块引用 open_dsc(path: "/path/to/dyld_shared_cache_arm64e", arch: "arm64e", module: "/usr/lib/libobjc.A.dylib", frameworks: ["/System/Library/Frameworks/Foundation.framework/Foundation"]) # 将另一个 DSC dylib 增量加载到已打开的数据库中 dsc_add_dylib(module: "/usr/lib/libSystem.B.dylib") # 按地址增量加载一个 DSC data/GOT/stub 区域 dsc_add_region(address: "0x180116000") # 在执行 dsc_add_dylib/dsc_add_region 后，确认分析就绪 analysis_status() ``` 要求： - `idat` 二进制文件（来自 IDA 安装）必须可通过 `$IDADIR` 或标准安装路径获取 - DSC 加载程序和 `dscu` 插件（随 IDA 9.x 捆绑提供） #### IDAPython 脚本 `run_script` 通过 IDA 的 IDAPython 引擎在打开的数据库中执行 Python 代码。stdout 和 stderr 会被捕获。 ``` # 内联脚本 run_script(code: "import idautils\nfor f in idautils.Functions():\n print(hex(f))") # 从磁盘运行一个 .py 文件 run_script(file: "/path/to/analysis_script.py") # 带超时设置（默认 120s，最大 600s） run_script(code: "import ida_bytes; print(ida_bytes.get_bytes(0x1000, 16).hex())", timeout_secs: 30) ``` 所有 `ida_*` 模块、`idc` 和 `idautils` 均可使用。请参阅 [IDAPython API 参考](https://python.docs.hex-rays.com)。 ## 上下文优化 `ida-mcp` 暴露了 71 个工具（约 10k 个 token 的 `tools/list` 负载）。具有 1M 上下文的前沿模型不会受此影响；而较小的模型以及不具备延迟工具加载功能的代理则会受到影响。您可以将工具表面过滤为仅包含您所需的内容： | 标志 | 环境变量 | 效果 | |---|---|---| | `--toolsets=cat1,cat2` | `IDA_MCP_TOOLSETS` | 将“所有工具”替换为所选类别的并集 | | `--tools=t1,t2` | `IDA_MCP_TOOLS` | 添加单个工具（在 `--toolsets` 基础上叠加） | | `--exclude-tools=t1,t2`| `IDA_MCP_EXCLUDE_TOOLS` | 从包含集中排除；优先级最高 | | `--read-only` | `IDA_MCP_READ_ONLY` | 剔除具有修改/任意代码执行功能的工具（`run_script`、`patch*`、`rename`、`set_comments`、类型/栈编辑、`dsc_add_*`、`analyze_funcs`）；保留生命周期/发现类工具 | 无标志 = 所有 71 个工具（默认）。类别：`core`、`functions`、`disassembly`、`decompile`、`xrefs`、`control_flow`、`memory`、`search`、`metadata`、`types`、`editing`、`scripting`（运行 `tool_catalog` 进行枚举）。标志会覆盖环境变量；未知的名称将在启动时被拒绝。 ### 按客户端推荐 - **Claude Code, Cursor：** 无需操作 — 两个客户端均已实现 MCP 工具模式的延迟加载。当工具占用超过 10% 的上下文时，Claude Code 的 MCP 工具搜索会自动延迟（Cursor 的动态上下文发现功能也类似）。 - **Codex CLI, OpenCode：** 每次会话都会消耗约 10k 个 token。请选择一个重点子集： ida-mcp --toolsets=core,functions,disassembly,decompile,xrefs - **Gemini CLI：** Gemini API 将所有 MCP 服务器的函数声明上限设定为 512 个。请压缩 `ida-mcp` 的体积，使其能与其他服务器并存： ida-mcp --toolsets=core,functions,disassembly,decompile --read-only - **小型 / 本地模型：** 建议使用最小的可用工具表面。用于初步分类时： ida-mcp --toolsets=core,functions --tools=decompile,callees,callers --read-only ### 通过 `mcpServers.json` 配置 大多数已安装的 MCP 配置会直接运行 `ida-mcp`，而不使用子命令。环境变量也适用于该运行路径： ``` { "mcpServers": { "ida-mcp": { "command": "ida-mcp", "env": { "IDA_MCP_TOOLSETS": "core,functions,disassembly,decompile,xrefs", "IDA_MCP_READ_ONLY": "true" } } } } ``` ### 测量 运行 `just measure-tools` 以查看每个工具的字符/token 分解。过滤不会改变此处报告的数值（它作用于协议边界），但差异会体现在您客户端的上下文视图中（在 Claude Code 中为 `/context`，其他客户端也有等效功能）。 ## 文档 - [docs/TOOLS.md](docs/TOOLS.md) - 工具目录与发现工作流 - [docs/TRANSPORTS.md](docs/TRANSPORTS.md) - 标准输入输出与可流式传输 HTTP (Streamable HTTP) - [docs/BUILDING.md](docs/BUILDING.md) - 从源码构建 - [docs/TESTING.md](docs/TESTING.md) - 运行测试 ## 许可证 MIT 版权所有 (c) 2026 **blacktop**

标签：AI, CTF工具, DAST, DLL 劫持, IDA Pro, LLM集成, MCP Server, Rust, Wayback Machine, 二进制分析, 云安全运维, 云资产清单, 反汇编, 可视化界面, 大语言模型, 恶意软件分析, 插件, 无头模式, 浏览器安全, 漏洞搜索, 网络流量审计, 自动化代码审查, 自动化分析, 跨站脚本, 逆向工程, 通知系统