Binary Ninja ヘッドレス MCP

ヘッドレスなBinary Ninjaサーバーで、MCP（Model Context Protocol）を話し、AIエージェントにGUIなしで深いリバースエンジニアリングワークフロー（逆アセンブル、IL、パッチ、型、相互参照など）への完全なアクセスを提供します。

エージェントランタイムと同じDockerコンテナ内で実行するように設計されています。サイドカーも追加サービスも不要です。

このプロジェクト全体（コード、テスト、ドキュメント）は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という名前のサーバーを登録します。
cwdがリポジトリルートの場合は、コマンドpython3と引数["binary_ninja_headless_mcp.py"]を使用するか、argsに絶対スクリプトパスを使用します。
samples/lsのような相対パスを正しく解決したい場合は、cwdをリポジトリパスに設定します。
ホストが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。

制限事項

Enterprise 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でシードセッションを開きます。

機能カタログ

サーバーは現在、36の機能グループにわたって181のツールを公開しています。

解析

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を取得します。

Binja

binja.info: Binary Ninjaのバージョン/インストール情報を返します。
binja.call: 汎用APIブリッジ：bn.*またはbv.*ターゲットパスを呼び出します。
binja.eval: bn、sessions、オプションのbvを使ってPythonコードを評価します。

データ

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

il.function: IL関数の一覧表示。
il.instruction_by_addr: ソースアドレスからIL命令を取得します。
il.address_to_index: アドレスをILインデックスにマッピングします。
il.index_to_address: ILインデックスをソースアドレスにマッピングします。
il.rewrite.capabilities: 1つの関数とILレベルのIL書き換えサポートを一覧表示します。
il.rewrite.noop_replace: no-op IL式置換を実行します。
il.rewrite.translate_identity: 恒等マッピングコールバックでILを変換します。

ローダー

loader.rebase: BinaryViewをリベースします。
loader.load_settings_types: ローダー設定タイプ名を一覧表示します。
loader.load_settings_get: ローダー設定値を取得します。
loader.load_settings_set: ローダー設定値を1つ設定します。

メモリ

memory.read: ビューからバイトを読み取ります（length <= 65536）。
memory.write: ビューにバイト（16進数）を書き込みます。
memory.insert: ビューにバイト（16進数）を挿入します。
memory.remove: ビューからバイトを削除します。
memory.reader_read: BinaryReaderを介して整数値を読み取ります。
memory.writer_write: BinaryWriterを介して整数値を書き込みます。

MCP

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: コンテキスト有効なプラグインコマンドを実行します。

プラグインリポジトリ

plugin_repo.status: プラグインリポジトリとプラグインの状態を一覧表示します。
plugin_repo.check_updates: プラグインリポジトリの更新を確認します。
plugin_repo.plugin_action: リポジトリプラグインに対してインストール/アンインストール/有効化/無効化アクションを実行します。

プロジェクト

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: 生のバイトパターン（16進文字列）を検索します。
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: 開いているセッションを1つ閉じます。
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: 追跡中の型アーカイブを1つ取得します。
type_archive.pull: 型アーカイブから型をプルします。
type_archive.push: 型を型アーカイブにプッシュします。
type_archive.references: 1つの型に対するアーカイブの着信/発信参照を照会します。

型ライブラリ

type_library.create: 型ライブラリを作成し、オプションでアタッチします。
type_library.load: 型ライブラリをロードし、オプションでアタッチします。
type_library.list: ビューにアタッチされた型ライブラリを一覧表示します。
type_library.get: 追跡中の型ライブラリを1つ取得します。

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