二进制忍者无头MCP

无头二进制忍者说话的服务器主控程序（模型上下文协议），使AI代理能够完全访问深度逆向工程工作流程——拆卸、IL、修补、类型、外部参照等——而无需GUI。

设计为在与代理运行时相同的Docker容器中运行。没有侧车，没有额外服务。

整个项目——代码、测试和文档——都是100%vibe编码的。

为什么

现有的Binary Ninja MCP服务器要么是GUI绑定的，要么暴露了有限的工具界面。此服务器仅为无头服务器，专为沙盒VM/容器环境中的代理驱动工作流而设计：代理可以完全控制分析系统，在您交互式讨论和指导过程的同时自动化大部分逆向工程。

目标是一个界面，代理可以在这个界面上随着时间的推移检查、改进和扩展分析——更新类型、符号和元数据，逐步改进分析数据库，应用补丁，使用撤销/重做安全迭代，并在工作流需要定制时运行自定义脚本。

特性

181工具 跨36个功能组：分析、反汇编、IL、修补、撤消/重做、类型、工作流、内存、搜索、外部参照、脚本等。
默认情况下为只读 具有安全的变异工作流程（撤消/重做、事务）。
脚本访问 通过 binja.eval 和 binja.call 对于工具目录未涵盖的任何内容。
标准和TCP传输。
零运行时依赖关系 除了Binary Ninja本身。
假冒后端模式 用于CI和开发，无需Binary Ninja许可证。

先决条件

python 3.11+
A. 二进制忍者使用无头许可证进行安装 binaryninja Python模块可在运行时导入（用于实际分析）
对于没有Binary Ninja的CI/CD开发，使用伪后端模式

安装

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

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

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

快速开始

标准传输（默认）：

python3 binary_ninja_headless_mcp.py

TCP传输：

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

伪后端模式（不需要二进制Ninja）：

python3 binary_ninja_headless_mcp.py --fake-backend

与AI代理一起使用

此服务器通过标准MCP进行通信 stdio （默认）或 tcp，因此任何支持MCP的代理主机都可以使用它。

克劳德代码

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 mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py

通用MCP主机

注册名为的服务器 binary_ninja_headless_mcp.
使用命令 python3 带args ["binary_ninja_headless_mcp.py"] 当 cwd 是repo根目录，或在中使用绝对脚本路径 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忍者运行时+许可证设置，并在配置了此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 和广泛的API访问 binja.call.
这是为可信的容器化代理环境设计的。
不要将此服务器直接暴露给不受信任的用户或网络。

本地开发工作流

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

功能引信

使用内置的MCP特征模糊器来练习宽阔的工具表面 samples/ls.

真正的二进制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.status：获取分析状态。
analysis.progress：获取分析进度快照。
analysis.update：触发异步分析更新。
analysis.update_and_wait：运行分析更新并等待完成。
analysis.abort：中止分析。
analysis.set_hold：保留/释放分析队列。

注释

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.info：获取架构和平台元数据。
arch.disasm_bytes：使用所选架构分解字节。
arch.assemble：使用选定的架构组装说明文本。

基址

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

二进制

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：列出地址处的函数。
binary.basic_blocks_at：按分页方式列出地址处的基本块。

比尼亚

binja.info：返回二进制Ninja版本/安装信息。
binja.call：通用API桥：调用 bn.* 或 bv.* 目标路径。
binja.eval：使用以下命令评估Python代码 bn, sessions，可选 bv.

数据

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

数据库

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

调试

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

反汇编

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

外部

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

函数

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.ping：健康检查。

他

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：不进行op IL表达置换。
il.rewrite.translate_identity：使用身份映射回调转换IL。

加载器

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

记忆

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

主控程序

mcp.response_format：解释工具结果字段(structuredContent 满载， content[0].text 摘要）。

元数据

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

补丁

patch.assemble：在地址处组装和修补指令字节。
patch.status：检查地址处的补丁可用性。
patch.convert_to_nop：支持时向NOP发送补丁指令。
patch.always_branch：修补条件分支，使其在支持时始终分支。
patch.never_branch：修补条件分支，使其在支持时从不分支。
patch.invert_branch：在支持的情况下，通过反转来修补条件分支。
patch.skip_and_return_value：补丁指令，在支持时跳过并返回值。

插件

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

插件_repo

plugin_repo.status：列出插件存储库和插件状态。
plugin_repo.check_updates：检查插件存储库更新。
plugin_repo.plugin_action：在存储库插件上运行install/uninstall/enable/disable操作。

项目

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

部分

section.add_user：添加用户部分。
section.remove_user：删除用户部分。

段

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

会话

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

任务

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

变换

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

类型

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.create：创建并可选择附加类型存档。
type_archive.open：打开并可选择附加类型存档。
type_archive.list：列出所附类型档案。
type_archive.get：获取一个跟踪类型存档。
type_archive.pull：从类型存档中提取类型。
type_archive.push：将类型推送到类型存档。
type_archive.references：查询一种类型的存档传入/传出引用。

类型库

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.begin：开始撤消事务。
undo.commit：提交撤消事务。
undo.revert：还原撤消事务。
undo.undo：执行撤消操作。
undo.redo：执行重做。

价值

value.reg：获取地址处/地址后的寄存器值。
value.stack：获取地址处/后面的堆栈内容。
value.possible：获取地址处设置的IL可能值。
value.flags_at：在某个地址获取解除的IL标志读/写状态。

工作流

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

交叉引用

xref.code_refs_to：对地址的代码引用。
xref.code_refs_from：地址中的代码引用。
xref.data_refs_to：对地址的数据引用。
xref.data_refs_from：来自地址的数据引用。

联系

如需更多信息，请联系Tim Blazytko(@mr_phrazer).

Binary Ninja Headless MCP

快速接入

详细介绍