Binary Ninja Headless MCP

Ein Headless-Binary Ninja-Server, der MCP (Model Context Protocol) spricht und KI-Agenten vollen Zugriff auf tiefgehende Reverse-Engineering-Workflows gibt – Disassemblierung, IL, Patching, Typen, Querverweise und mehr – ohne GUI.

Entwickelt, um im gleichen Docker-Container wie die Agenten-Laufzeitumgebung zu laufen. Keine Sidecars, keine zusätzlichen Dienste.

Dieses gesamte Projekt – Code, Tests und Dokumentation – ist zu 100 % Vibe-coded.

Warum

Existierende Binary Ninja MCP-Server sind entweder GUI-gebunden oder bieten nur eine begrenzte Werkzeugoberfläche. Dieser Server ist ausschließlich headless und für agentengesteuerte Workflows in sandbox-VM/Containerumgebungen konzipiert: Der Agent erhält die vollständige Kontrolle über das Analysesystem, automatisiert große Teile des Reverse Engineerings, während Sie interaktiv diskutieren und den Prozess steuern.

Das Ziel ist eine Schnittstelle, bei der Agenten eine Analyse im Laufe der Zeit inspizieren, verfeinern und erweitern können – Aktualisieren von Typen, Symbolen und Metadaten, inkrementelles Verbessern der Analysedatenbank, Anwenden von Patches und sicheres Iterieren mit Rückgängig/Wiederholen sowie Ausführen benutzerdefinierter Skripte, wenn ein Workflow etwas Maßgeschneidertes benötigt.

Funktionen

• 181 Werkzeuge in 36 Funktionsgruppen: Analyse, Disassemblierung, IL, Patching, Rückgängig/Wiederholen, Typen, Workflows, Speicher, Suche, Querverweise, Skripting und mehr.
• Standardmäßig schreibgeschützt mit sicheren Mutations-Workflows (Rückgängig/Wiederholen, Transaktionen).
• Skriptzugriff über binja.eval und binja.call für alles, was der Werkzeugkatalog nicht abdeckt.
• Stdio- und TCP-Transporte.
• Keine Laufzeitabhängigkeiten außer Binary Ninja selbst.
• Fake-Backend-Modus für CI und Entwicklung ohne Binary Ninja-Lizenz.

Voraussetzungen

• Python 3.11+
• Eine Binary Ninja-Installation mit einer headless-fähigen Lizenz und dem importierbaren binaryninja-Python-Modul in Ihrer Laufzeitumgebung (für echte Analyse)
• Für CI/Entwicklung ohne Binary Ninja verwenden Sie den Fake-Backend-Modus

Installation

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

Oder direkt aus dem Repository-Root installieren ohne Klonen:

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

Schnellstart

Stdio-Transport (Standard):

python3 binary_ninja_headless_mcp.py

TCP-Transport:

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

Fake-Backend-Modus (kein Binary Ninja erforderlich):

python3 binary_ninja_headless_mcp.py --fake-backend

Verwendung mit KI-Agenten

Dieser Server spricht standardmäßig MCP über stdio (Standard) oder tcp, sodass jeder MCP-fähige Agenten-Host ihn nutzen kann.

Claude Code

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

Oder fügen Sie es der .mcp.json Ihres Projekts hinzu:

{
  "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

Generischer MCP-Host

• Registrieren Sie einen Server mit dem Namen binary_ninja_headless_mcp.
• Verwenden Sie den Befehl python3 mit den Argumenten ["binary_ninja_headless_mcp.py"] wenn cwd das Repository-Root ist, oder verwenden Sie einen absoluten Skriptpfad in args.
• Setzen Sie cwd auf den Repository-Pfad, wenn relative Pfade wie samples/ls korrekt aufgelöst werden sollen.
• Verwenden Sie den Stdio-Transport, es sei denn, Ihr Host erfordert TCP.
• Für den Fake-Modus (kein Binary Ninja installiert) fügen Sie --fake-backend hinzu.
• Überprüfen Sie die Konnektivität durch Aufrufen von health.ping, dann session.open.

Docker-Co-Location-Muster

Empfohlenes Bereitstellungsmodell: Führen Sie den Agentenprozess und diesen MCP-Server im selben Container-Image aus.

Beispiel-Basisimage:

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"]

Falls Sie eine echte Binary Ninja-Analyse im Container benötigen, fügen Sie Ihre Binary Ninja-Laufzeitumgebung und Lizenz im selben Image hinzu und starten Sie den Agenten mit diesem konfigurierten MCP-Server.

MCP-Methoden

• initialize
• ping
• tools/list
• tools/call
• shutdown

Verhalten von tools/list:

• Ohne explizite Paginierungsparameter wird der vollständige Werkzeugkatalog zurückgegeben.
• Wenn offset oder limit angegeben ist, wird eine seitenweise Ausgabe verwendet (offset=0, limit=50 Standard im Seitenmodus).
• Unterstützt Filterung über:
  • prefix (z. B. binary.)
  • query (Teilstring-Übereinstimmung mit Werkzeugname/-beschreibung)
• Gibt Paginierungsmetadaten zurück: offset, limit, total, has_more.
• Wenn eine Seite abgeschnitten ist (has_more=true), werden next_offset und ein notice-Hinweis eingefügt.

Verhalten von Werkzeugaufruf-Antworten:

• structuredContent ist die kanonische vollständige Nutzlast.
• content[0].text ist eine kompakte Zusammenfassungszeichenfolge (keine vollständige JSON-Duplizierung).
• Diese Aufteilung ist beabsichtigt, um den Kontextverbrauch gering zu halten und gleichzeitig vollständige maschinenlesbare Daten bereitzustellen.

Qualität und Tests

Dieses Repository ist gut getestet und hat durchgesetzte Qualitätsgates.

• Testsuite: Führen Sie pytest --collect-only -q für die aktuelle Anzahl der gesammelten Tests aus.
• CI-Workflow erzwingt:
  • ruff format --check .
  • ruff check .
  • pytest
• CI verwendet BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1, sodass Prüfungen ohne Binary Ninja-Installation ausgeführt werden können.
• Zusätzliche strukturelle Tests überprüfen die Konsistenz des Werkzeugregisters und die Erreichbarkeit des Backends.

Kontextsteuerung

• Der schreibgeschützte Modus ist die Standardeinstellung für geöffnete Sitzungen (read_only=true).
• binary.basic_blocks_at und function.basic_blocks werden seitenweise ausgegeben (offset/limit).
• memory.read hat eine harte Antwortbegrenzung: length ≤ 65536.

Einschränkungen

• Enterprise-APIs werden derzeit nicht abgedeckt.
• Debugger-APIs werden derzeit nicht abgedeckt.

Sicherheitsmodell

• Die MCP-Kommunikation (stdio/tcp) ist standardmäßig nicht authentifiziert.
• Der Server ermöglicht beliebiges Scripting über binja.eval und breiten API-Zugriff über binja.call.
• Dies ist absichtlich für vertrauenswürdige, containerisierte Agentenumgebungen so konzipiert.
• Setzen Sie diesen Server nicht direkt ungeschützten Benutzern oder Netzwerken aus.

Lokaler Entwicklungs-Workflow

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

Feature-Fuzzer

Verwenden Sie den integrierten MCP-Feature-Fuzzer, um eine breite Werkzeugoberfläche gegen samples/ls zu testen.

Echtes Binary Ninja-Backend:

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

Fake-Backend-Smoke-Test:

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

JSON-Coverage-Bericht schreiben:

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

Nützliche Flags:

• --min-success-tools N: Beendet sich mit einem Fehler, wenn weniger als N Werkzeuge erfolgreich waren.
• --verbose: Gibt jeden Werkzeugaufruf während des Fuzzings aus.
• --update-analysis: Öffnet die Seedsitzung mit update_analysis=true.

Funktionskatalog

Der Server stellt derzeit 181 Werkzeuge in 36 Funktionsgruppen bereit.

analysis

• analysis.status: Analysestatus abrufen
• analysis.progress: Analysestand-Momentaufnahme abrufen
• analysis.update: Asynchrone Analyseaktualisierung auslösen
• analysis.update_and_wait: Analyseaktualisierung ausführen und auf Abschluss warten
• analysis.abort: Analyse abbrechen
• analysis.set_hold: Analysewarteschlange anhalten/freigeben

annotation

• annotation.rename_function: Funktion umbenennen
• annotation.rename_symbol: Symbol an Adresse umbenennen
• annotation.undefine_symbol: Benutzersymbol an Adresse undefinieren
• annotation.define_symbol: Symbol an Adresse definieren
• annotation.rename_data_var: Datenvariable umbenennen
• annotation.define_data_var: Datenvariable definieren
• annotation.undefine_data_var: Datenvariable undefinieren
• annotation.set_comment: Kommentar an Adresse setzen
• annotation.get_comment: Kommentar an Adresse abrufen
• annotation.add_tag: Benutzerdaten-Tag an Adresse hinzufügen
• annotation.get_tags: Tags an Adresse abrufen

arch

• arch.info: Architektur- und Plattformmetadaten abrufen
• arch.disasm_bytes: Bytes mit ausgewählter Architektur disassemblieren
• arch.assemble: Befehlstext mit ausgewählter Architektur assemblieren

baseaddr

• baseaddr.detect: Basisadresserkennung ausführen
• baseaddr.reasons: Gründe für Basisadresserkennung abrufen
• baseaddr.abort: Basisadresserkennung abbrechen

binary

• binary.summary: Binär-/Sitzungszusammenfassung abrufen
• binary.save: Aktuelle Binäransicht in einem Dateipfad speichern
• binary.functions: Funktionen seitenweise auflisten
• binary.strings: Gefundene Zeichenketten seitenweise auflisten
• binary.search_text: Rohtext/-bytes in einer Sitzung durchsuchen
• binary.sections: Abschnitte seitenweise auflisten
• binary.segments: Segmente seitenweise auflisten
• binary.symbols: Symbole seitenweise auflisten
• binary.data_vars: Datenvariablen seitenweise auflisten
• binary.get_function_at: Funktion anhand der Adresse finden
• binary.get_function_disassembly_at: Vollständige Disassemblierung für die Funktion abrufen, die eine Adresse enthält
• binary.get_function_il_at: Vollständige IL für die Funktion abrufen, die eine Adresse enthält

binja

• binja.info: Binary Ninja-Version/Installationsinfo zurückgeben
• binja.call: Generische API-Brücke: bn.* oder bv.* Zielpfad aufrufen
• binja.eval: Python-Code mit bn, sessions und optionalem bv auswerten

data

• data.typed_at: Typisierte Datenvariable an einer Adresse abrufen

database

• database.create_bndb: .bndb aus Sitzung erstellen
• database.save_auto_snapshot: Automatische Momentaufnahme speichern
• database.info: Datenbankstatus für Sitzung abrufen
• database.snapshots: Datenbank-Momentaufnahmen auflisten
• database.read_global: Globalen Datenbank-String-Schlüssel lesen
• database.write_global: Globalen Datenbank-String-Schlüssel schreiben

debug

• debug.parsers: Für diese Ansicht gültige Debuginfo-Parser auflisten
• debug.parse_and_apply: Debuginfo parsen und auf die Ansicht anwenden

disasm

• disasm.linear: Lineare Disassemblierungszeilen abrufen
• disasm.function: Vollständige Disassemblierung für die Funktion abrufen, die eine Adresse enthält
• disasm.range: Disassemblierungszeilen für einen Adressbereich

external

• external.library_add: Externe Bibliothek hinzufügen
• external.library_list: Externe Bibliotheken auflisten
• external.library_remove: Externe Bibliothek entfernen
• external.location_add: Externe Standortzuordnung hinzufügen
• external.location_get: Externe Standortzuordnung abrufen
• external.location_remove: Externe Standortzuordnung entfernen

function

• function.basic_blocks: Grundblöcke in einer Funktion seitenweise auflisten
• function.callers: Aufrufer einer Funktion
• function.callees: Aufgerufene einer Funktion
• function.variables: Funktionsvariablen auflisten
• function.var_refs: Variablenreferenzen in MLIL/HLIL auflisten
• function.var_refs_from: Variablenreferenzen, die von einer Adresse ausgehen, auflisten
• function.ssa_var_def_use: SSA-Variablendefinition und -verwendungen abrufen
• function.ssa_memory_def_use: SSA-Speicherdefinition und -verwendungen nach Speicherversion abrufen
• function.metadata_store: Funktionsmetadaten nach Schlüssel speichern
• function.metadata_query: Funktionsmetadaten nach Schlüssel abfragen
• function.metadata_remove: Funktionsmetadaten nach Schlüssel entfernen

health

• health.ping: Gesundheitsprüfung

il

• il.function: IL-Funktionsliste
• il.instruction_by_addr: IL-Befehl nach Quelladresse abrufen
• il.address_to_index: Adresse auf IL-Index/Indizes abbilden
• il.index_to_address: IL-Index auf Quelladresse abbilden
• il.rewrite.capabilities: IL-Umschreibungsunterstützung für eine Funktion und IL-Ebene auflisten
• il.rewrite.noop_replace: No-op-IL-Ausdrucksersetzung durchführen
• il.rewrite.translate_identity: IL mit Identitätszuordnungs-Callback übersetzen

loader

• loader.rebase: BinaryView neu basieren
• loader.load_settings_types: Typnamen der Ladeeinstellungen auflisten
• loader.load_settings_get: Werte der Ladeeinstellungen abrufen
• loader.load_settings_set: Einen Ladeeinstellungswert setzen

memory

• memory.read: Bytes aus der Ansicht lesen (length <= 65536)
• memory.write: Bytes (hex) in die Ansicht schreiben
• memory.insert: Bytes (hex) in die Ansicht einfügen
• memory.remove: Bytes aus der Ansicht entfernen
• memory.reader_read: Ganzzahlwerte über BinaryReader lesen
• memory.writer_write: Ganzzahlwerte über BinaryWriter schreiben

mcp

• mcp.response_format: Erklärt Werkzeug-Ergebnisfelder (structuredContent vollständige Nutzlast, content[0].text Zusammenfassung)

metadata

• metadata.store: Metadaten nach Schlüssel speichern
• metadata.query: Metadaten nach Schlüssel abfragen
• metadata.remove: Metadaten nach Schlüssel entfernen

patch

• patch.assemble: Befehlsbytes an Adresse assemblieren und patchen
• patch.status: Patch-Verfügbarkeit an Adresse überprüfen
• patch.convert_to_nop: Befehl auf NOP patchen, wenn unterstützt
• patch.always_branch: Bedingten Sprung auf immer springen patchen, wenn unterstützt
• patch.never_branch: Bedingten Sprung auf nie springen patchen, wenn unterstützt
• patch.invert_branch: Bedingten Sprung durch Invertierung patchen, wenn unterstützt
• patch.skip_and_return_value: Befehl auf Überspringen und Wert zurückgeben patchen, wenn unterstützt

plugin

• plugin.valid_commands: Kontextgültige Plugin-Befehle auflisten
• plugin.execute: Kontextgültigen Plugin-Befehl ausführen

plugin_repo

• plugin_repo.status: Plugin-Repositories und Plugin-Status auflisten
• plugin_repo.check_updates: Plugin-Repository-Updates überprüfen
• plugin_repo.plugin_action: Installations-/Deinstallations-/Aktivierungs-/Deaktivierungsaktion für Repository-Plugin ausführen

project

• project.create: Projekt erstellen
• project.open: Projekt öffnen
• project.close: Verfolgtes Projekt schließen
• project.list: Projektordner/-dateien auflisten
• project.create_folder: Projektordner erstellen
• project.create_file: Projektdatei aus Base64-Daten erstellen
• project.metadata_store: Projektmetadaten speichern
• project.metadata_query: Projektmetadaten abfragen
• project.metadata_remove: Projektmetadaten entfernen

search

• search.data: Nach rohen Bytesmustern suchen (Hex-String)
• search.next_text: Nächste Textübereinstimmung finden
• search.all_text: Alle Textübereinstimmungen im Bereich finden (Regex optional)
• search.next_data: Nächste Daten-/Bytesmuster-Übereinstimmung finden
• search.all_data: Alle Daten-/Bytesmuster-Übereinstimmungen im Bereich finden
• search.next_constant: Nächstes Konstantenvorkommen finden
• search.all_constant: Alle Konstantenvorkommen im Bereich finden

section

• section.add_user: Benutzerabschnitt hinzufügen
• section.remove_user: Benutzerabschnitt entfernen

segment

• segment.add_user: Benutzersegment hinzufügen
• segment.remove_user: Benutzersegment entfernen

session

• session.open: Binärdatei öffnen und Sitzung erstellen
• session.open_bytes: Binärsitzung aus Base64-kodierten Bytes öffnen
• session.open_existing: Weitere Sitzung aus der Datei einer bestehenden Sitzung öffnen
• session.close: Eine offene Sitzung schließen
• session.list: Offene Sitzungen auflisten
• session.mode: Sicherheits-/Determinismusmodus der Sitzung abrufen
• session.set_mode: Sicherheits-/Determinismusmodus der Sitzung aktualisieren

task

• task.analysis_update: Asynchrone Analyseaktualisierungsaufgabe starten
• task.search_text: Asynchrone Suchaufgabe starten
• task.status: Aufgabenstatus abrufen
• task.result: Aufgabenergebnis abrufen
• task.cancel: Aufgabe abbrechen (bestmöglich)

transform

• transform.inspect: Transformations-Extraktionspipeline inspizieren/verarbeiten

type

• type.parse_string: Einzelnen Typ-String parsen
• type.parse_declarations: C-Deklarationen für Typen/Variablen/Funktionen parsen
• type.define_user: Benutzertyp aus Typquelle definieren
• type.rename: Typ umbenennen
• type.undefine_user: Benutzertyp undefinieren
• type.import_library_type: Typ aus Typbibliothek importieren
• type.import_library_object: Objekttyp aus Typbibliothek importieren
• type.export_to_library: Typ in Typbibliothek exportieren

type_archive

• type_archive.create: Typarchiv erstellen und optional anhängen
• type_archive.open: Typarchiv öffnen und optional anhängen
• type_archive.list: Angehängte Typarchive auflisten
• type_archive.get: Ein verfolgtes Typarchiv abrufen
• type_archive.pull: Typen aus einem Typarchiv ziehen
• type_archive.push: Typen in ein Typarchiv schieben
• type_archive.references: Eingehende/ausgehende Archivreferenzen für einen Typ abfragen

type_library

• type_library.create: Typbibliothek erstellen und optional anhängen
• type_library.load: Typbibliothek laden und optional anhängen
• type_library.list: An die Ansicht angehängte Typbibliotheken auflisten
• type_library.get: Eine verfolgte Typbibliothek abrufen

uidf

• uidf.parse_possible_value: Benutzerinformierten möglichen Wertsatz-String parsen
• uidf.set_user_var_value: Funktionsbenutzervariablenwert setzen
• uidf.clear_user_var_value: Funktionsbenutzervariablenwert löschen
• uidf.list_user_var_values: Alle Benutzervariablenwerte für eine Funktion auflisten

undo

• undo.begin: Rückgängig-Transaktion beginnen
• undo.commit: Rückgängig-Transaktion festschreiben
• undo.revert: Rückgängig-Transaktion rückgängig machen
• undo.undo: Rückgängig durchführen
• undo.redo: Wiederholen durchführen

value

• value.reg: Registerwert an/nach einer Adresse abrufen
• value.stack: Stack-Inhalte an/nach einer Adresse abrufen
• value.possible: Möglichen IL-Wertsatz an einer Adresse abrufen
• value.flags_at: Gelifteten IL-Flag-Lese-/Schreibzustand an einer Adresse abrufen

workflow

• workflow.list: Registrierte Workflows auflisten
• workflow.describe: Workflow-Topologie und -Einstellungen beschreiben
• workflow.clone: Workflow klonen
• workflow.insert: Aktivitäten vor einer Aktivität einfügen
• workflow.insert_after: Aktivitäten nach einer Aktivität einfügen
• workflow.remove: Workflow-Aktivität entfernen
• workflow.graph: Workflow-Graphen zusammenfassen
• workflow.machine.status: Workflow-Maschinenstatus abrufen
• workflow.machine.control: Workflow-Maschinenlaufzeit steuern

xref

• xref.code_refs_to: Code-Referenzen auf eine Adresse
• xref.code_refs_from: Code-Referenzen von einer Adresse
• xref.data_refs_to: Datenreferenzen auf eine Adresse
• xref.data_refs_from: Datenreferenzen von einer Adresse

Kontakt

Für weitere Informationen kontaktieren Sie Tim Blazytko (@mr_phrazer).