Binary Ninja Headless MCP

一个无头 Binary Ninja 服务器，支持 MCP（模型上下文协议），让 AI 智能体能够完全访问深度逆向工程工作流程——反汇编、IL、补丁、类型、交叉引用等——无需 GUI。

设计为与智能体运行时运行在同一 Docker 容器中。无需 Sidecar，无需额外服务。

整个项目——代码、测试和文档——100% 由感觉驱动编码。

为什么

现有的 Binary Ninja MCP 服务器要么受限于 GUI，要么暴露有限的工具面。此服务器仅支持无头模式，专为沙盒 VM/容器环境中的智能体驱动工作流程设计：智能体完全控制分析系统，自动完成大量逆向工程部分，而您可以交互式讨论和引导整个过程。

目标是提供一个界面，让智能体能够随时间检查、优化和扩展分析——更新类型、符号和元数据，增量改进分析数据库，安全地应用补丁并通过撤销/重做进行迭代，以及在需要自定义工作流程时运行自定义脚本。

功能

181 个工具，分布在 36 个功能组：分析、反汇编、IL、补丁、撤销/重做、类型、工作流程、内存、搜索、交叉引用、脚本等。
默认只读，支持安全的修改工作流程（撤销/重做、事务）。
脚本访问：通过 binja.eval 和 binja.call 覆盖工具目录未涵盖的所有内容。
支持 Stdio 和 TCP 传输。
零运行时依赖，仅需 Binary Ninja 本身。
假后端模式：适用于无需 Binary Ninja 许可证的 CI 和开发。

前提条件

Python 3.11+
已安装 Binary Ninja，并具有支持无头模式的许可证，且 binaryninja Python 模块可在运行时导入（用于真实分析）
对于无需 Binary Ninja 的 CI/开发，请使用假后端模式

安装

git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .

或者直接从仓库根目录安装，无需克隆：

pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git

快速开始

Stdio 传输（默认）：

python3 binary_ninja_headless_mcp.py

TCP 传输：

python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765

假后端模式（无需 Binary Ninja）：

python3 binary_ninja_headless_mcp.py --fake-backend

与 AI 智能体一起使用

此服务器支持标准 MCP，通过 stdio（默认）或 tcp 通信，因此任何支持 MCP 的智能体宿主均可使用。

Claude Code

claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py

或者将其添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "binary_ninja_headless_mcp": {
      "command": "python3",
      "args": ["binary_ninja_headless_mcp.py"],
      "cwd": "/path/to/binary-ninja-headless-mcp"
    }
  }
}

Codex

codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py

通用 MCP 宿主

注册一个名为 binary_ninja_headless_mcp 的服务器。
使用命令 python3，参数为 ["binary_ninja_headless_mcp.py"]，并将 cwd 设置为仓库根目录，或者在 args 中使用绝对脚本路径。
设置 cwd 为仓库路径，以便相对路径（如 samples/ls）能正确解析。
除非宿主要求 TCP，否则使用 stdio 传输。
对于假模式（未安装 Binary Ninja），添加 --fake-backend。
通过调用 health.ping 验证连接，然后调用 session.open。

Docker 共置模式

推荐的部署模型：将智能体进程和此 MCP 服务器放在同一个容器镜像中。

基础示例：

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]

如果需要在容器内进行真实的 Binary Ninja 分析，请在该镜像中添加 Binary Ninja 运行时和许可证设置，并启动配置了此 MCP 服务器的智能体。

MCP 方法

initialize
ping
tools/list
tools/call
shutdown

tools/list 行为：

无显式分页参数时，返回完整工具目录。
如果提供了 offset 或 limit，则使用分页输出（分页模式下默认为 offset=0，limit=50）。
支持通过以下方式过滤：
- prefix（例如 binary.）
- query（子字符串匹配工具名称/描述）
返回分页元数据：offset、limit、total、has_more。
当页面被截断时（has_more=true），包含 next_offset 和 notice 提示。

工具调用响应行为：

structuredContent 是规范的完整有效负载。
content[0].text 是紧凑的摘要字符串（不重复完整 JSON）。
这种拆分是故意的，旨在保持上下文使用量较小的同时，仍暴露完整的机器可读数据。

质量与测试

此仓库经过充分测试，并强制执行质量门禁。

测试套件：运行 pytest --collect-only -q 查看当前收集的测试数量。
CI 工作流程强制执行：
- ruff format --check .
- ruff check .
- pytest
CI 使用 BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1，因此检查无需安装 Binary Ninja 即可运行。
额外的结构测试验证工具注册表的一致性和后端的可达性。

上下文控制

只读模式是打开会话的默认模式（read_only=true）。
binary.basic_blocks_at 和 function.basic_blocks 支持分页（offset/limit）。
memory.read 有硬性响应上限：length <= 65536。

限制

企业级 API 当前未覆盖。
调试器 API 当前未覆盖。

安全模型

MCP 通信（stdio/tcp）默认未经过身份验证。
服务器通过 binja.eval 暴露任意脚本访问，通过 binja.call 暴露广泛的 API 访问。
这是为受信任的容器化智能体环境有意设计的。
请勿将此服务器直接暴露给不受信任的用户或网络。

本地开发工作流程

ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q

功能模糊测试器

使用内置的 MCP 功能模糊测试器，针对 samples/ls 执行广泛的工具面测试。

真实 Binary Ninja 后端：

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337

假后端冒烟测试：

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20

生成 JSON 覆盖率报告：

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json

有用的标志：

--min-success-tools N：如果成功工具少于 N 个，则非零退出。
--verbose：模糊测试时打印每个工具调用。
--update-analysis：使用 update_analysis=true 打开种子会话。

功能目录

服务器当前公开 181 个工具，分布在 36 个功能组中。

analysis

analysis.status：获取分析状态。
analysis.progress：获取分析进度快照。
analysis.update：触发异步分析更新。
analysis.update_and_wait：运行分析更新并等待完成。
analysis.abort：终止分析。
analysis.set_hold：暂停/恢复分析队列。

annotation

annotation.rename_function：重命名一个函数。
annotation.rename_symbol：重命名指定地址处的符号。
annotation.undefine_symbol：取消定义指定地址处的用户符号。
annotation.define_symbol：定义指定地址处的符号。
annotation.rename_data_var：重命名数据变量。
annotation.define_data_var：定义数据变量。
annotation.undefine_data_var：取消定义数据变量。
annotation.set_comment：设置指定地址处的注释。
annotation.get_comment：获取指定地址处的注释。
annotation.add_tag：添加用户数据标签到指定地址。
annotation.get_tags：获取指定地址处的标签。

arch

arch.info：获取架构和平台元数据。
arch.disasm_bytes：使用所选架构反汇编字节。
arch.assemble：使用所选架构汇编指令文本。

baseaddr

baseaddr.detect：运行基地址检测。
baseaddr.reasons：获取基地址检测原因。
baseaddr.abort：终止基地址检测。

binary

binary.summary：获取二进制/会话摘要。
binary.save：将当前二进制视图保存到文件路径。
binary.functions：列出函数（支持分页）。
binary.strings：列出已发现的字符串（支持分页）。
binary.search_text：在会话中搜索原始文本/字节。
binary.sections：列出节（支持分页）。
binary.segments：列出段（支持分页）。
binary.symbols：列出符号（支持分页）。
binary.data_vars：列出数据变量（支持分页）。
binary.get_function_at：根据地址查找函数。
binary.get_function_disassembly_at：获取包含某地址的函数的完整反汇编。
binary.get_function_il_at：获取包含某地址的函数的完整 IL。
binary.functions_at：列出某地址处的函数。

binja

binja.info：返回 Binary Ninja 版本/安装信息。
binja.call：通用 API 桥：调用 bn.* 或 bv.* 目标路径。
binja.eval：使用 bn、sessions 和可选的 bv 评估 Python 代码。

data

data.typed_at：获取指定地址处的类型化数据变量。

database

database.create_bndb：从会话创建 .bndb。
database.save_auto_snapshot：保存自动快照。
database.info：获取会话的数据库状态。
database.snapshots：列出数据库快照。
database.read_global：读取数据库全局字符串键。
database.write_global：写入数据库全局字符串键。

debug

debug.parsers：列出对此视图有效的调试信息解析器。
debug.parse_and_apply：解析调试信息并将其应用于视图。

disasm

disasm.linear：获取线性反汇编行。
disasm.function：获取包含某地址的函数的完整反汇编。
disasm.range：地址范围反汇编行。

external

external.library_add：添加外部库。
external.library_list：列出外部库。
external.library_remove：移除外部库。
external.location_add：添加外部位置映射。
external.location_get：获取外部位置映射。
external.location_remove：移除外部位置映射。

function

function.basic_blocks：列出函数中的基本块（支持分页）。
function.callers：函数的调用者。
function.callees：函数的被调用者。
function.variables：列出函数变量。
function.var_refs：列出 MLIL/HLIL 中的变量引用。
function.var_refs_from：列出从某地址出发的变量引用。
function.ssa_var_def_use：获取 SSA 变量定义和使用。
function.ssa_memory_def_use：获取按内存版本划分的 SSA 内存定义和使用。
function.metadata_store：按键存储函数元数据。
function.metadata_query：按键查询函数元数据。
function.metadata_remove：按键移除函数元数据。

health

health.ping：健康检查。

il

il.function：IL 函数列表。
il.instruction_by_addr：根据源地址获取 IL 指令。
il.address_to_index：将地址映射到 IL 索引。
il.index_to_address：将 IL 索引映射到源地址。
il.rewrite.capabilities：列出函数和 IL 级别的 IL 重写支持。
il.rewrite.noop_replace：执行空操作 IL 表达式替换。
il.rewrite.translate_identity：使用恒等映射回调翻译 IL。

loader

loader.rebase：重新基址 BinaryView。
loader.load_settings_types：列出加载器设置类型名称。
loader.load_settings_get：获取加载器设置值。
loader.load_settings_set：设置一个加载器设置值。

memory

memory.read：从视图中读取字节（length <= 65536）。
memory.write：将字节（十六进制）写入视图。
memory.insert：将字节（十六进制）插入视图。
memory.remove：从视图中移除字节。
memory.reader_read：通过 BinaryReader 读取整数值。
memory.writer_write：通过 BinaryWriter 写入整数值。

mcp

mcp.response_format：解释工具结果字段（structuredContent 完整有效负载，content[0].text 摘要）。

metadata

metadata.store：按键存储元数据。
metadata.query：按键查询元数据。
metadata.remove：按键移除元数据。

patch

patch.assemble：汇编并修补指定地址的指令字节。
patch.status：检查指定地址的修补可用性。
patch.convert_to_nop：在支持时，将指令修补为 NOP。
patch.always_branch：在支持时，将条件分支修补为始终分支。
patch.never_branch：在支持时，将条件分支修补为从不分支。
patch.invert_branch：在支持时，通过反转修补条件分支。
patch.skip_and_return_value：在支持时，将指令修补为跳过并返回值。

plugin

plugin.valid_commands：列出上下文有效的插件命令。
plugin.execute：执行上下文有效的插件命令。

plugin_repo

plugin_repo.status：列出插件仓库和插件状态。
plugin_repo.check_updates：检查插件仓库更新。
plugin_repo.plugin_action：对仓库插件执行安装/卸载/启用/禁用操作。

project

project.create：创建项目。
project.open：打开项目。
project.close：关闭跟踪的项目。
project.list：列出项目文件夹/文件。
project.create_folder：创建项目文件夹。
project.create_file：从 base64 数据创建项目文件。
project.metadata_store：存储项目元数据。
project.metadata_query：查询项目元数据。
project.metadata_remove：移除项目元数据。

search

search.data：搜索原始字节模式（十六进制字符串）。
search.next_text：查找下一个文本匹配。
search.all_text：在范围内查找所有文本匹配（可选正则表达式）。
search.next_data：查找下一个数据/字节模式匹配。
search.all_data：在范围内查找所有数据/字节模式匹配。
search.next_constant：查找下一个常量出现。
search.all_constant：在范围内查找所有常量出现。

section

section.add_user：添加用户节。
section.remove_user：移除用户节。

segment

segment.add_user：添加用户段。
segment.remove_user：移除用户段。

session

session.open：打开二进制文件并创建会话。
session.open_bytes：从 base64 编码的字节打开二进制会话。
session.open_existing：从现有会话的文件打开另一个会话。
session.close：关闭一个打开的会话。
session.list：列出打开的会话。
session.mode：获取会话安全/确定性模式。
session.set_mode：更新会话安全/确定性模式。

task

task.analysis_update：启动异步分析更新任务。
task.search_text：启动异步搜索任务。
task.status：获取任务状态。
task.result：获取任务结果。
task.cancel：取消任务（尽力而为）。

transform

transform.inspect：检查/处理转换提取管道。

type

type.parse_string：解析单个类型字符串。
type.parse_declarations：解析类型的 C 声明/变量/函数。
type.define_user：从类型源定义用户类型。
type.rename：重命名一个类型。
type.undefine_user：取消定义用户类型。
type.import_library_type：从类型库导入类型。
type.import_library_object：从类型库导入对象类型。
type.export_to_library：将类型导出到类型库。

type_archive

type_archive.create：创建并可选地附加一个类型存档。
type_archive.open：打开并可选地附加一个类型存档。
type_archive.list：列出附加的类型存档。
type_archive.get：获取一个跟踪的类型存档。
type_archive.pull：从类型存档拉取类型。
type_archive.push：将类型推送到类型存档。
type_archive.references：查询一个类型的入站/出站存档引用。

type_library

type_library.create：创建并可选地附加一个类型库。
type_library.load：加载并可选地附加一个类型库。
type_library.list：列出附加到视图的类型库。
type_library.get：获取一个跟踪的类型库。

uidf

uidf.parse_possible_value：解析用户提供的可能值集字符串。
uidf.set_user_var_value：设置函数用户变量值。
uidf.clear_user_var_value：清除函数用户变量值。
uidf.list_user_var_values：列出函数的所有用户变量值。

undo

undo.begin：开始撤销事务。
undo.commit：提交撤销事务。
undo.revert：回滚撤销事务。
undo.undo：执行撤销。
undo.redo：执行重做。

value

value.reg：获取在/之后某地址的寄存器值。
value.stack：获取在/之后某地址的堆栈内容。
value.possible：获取某地址的 IL 可能值集。
value.flags_at：获取某地址处提升的 IL 标志读/写状态。

workflow

workflow.list：列出已注册的工作流程。
workflow.describe：描述工作流程拓扑和设置。
workflow.clone：克隆工作流程。
workflow.insert：在活动之前插入活动。
workflow.insert_after：在活动之后插入活动。
workflow.remove：移除工作流程活动。
workflow.graph：总结工作流程图。
workflow.machine.status：获取工作流程机状态。
workflow.machine.control：控制工作流程机运行时。

xref

xref.code_refs_to：对某地址的代码引用。
xref.code_refs_from：从某地址出发的代码引用。
xref.data_refs_to：对某地址的数据引用。
xref.data_refs_from：从某地址出发的数据引用。

联系方式

更多信息，请联系 Tim Blazytko（@mr_phrazer）。

binary-ninja-headless-mcp

最受欢迎