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を取得します。
• binary.functions_at: アドレスにある関数を一覧表示します。
• binary.basic_blocks_at: アドレスにある基本ブロックをページネーション付きで一覧表示します。

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: アドレス範囲の逆アセンブリ行を取得します。