二进制忍者无头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. 二进制忍者 使用无头许可证进行安装
binaryninjaPython模块可在运行时导入（用于实际分析） - 对于没有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.pyTCP传输：
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方法
initializepingtools/listtools/callshutdown
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).