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

python3 binary_ninja_headless_mcp.py

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

python3 binary_ninja_headless_mcp.py --fake-backend

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

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

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

ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q
## Fuzzer de Características

Usa el fuzzer de características MCP incorporado para ejercitar una amplia superficie de herramientas contra `samples/ls`.

Backend real Binary Ninja:

```bash
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

python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json
## Banderas útiles:

- `--min-success-tools N`: sale con código no cero si menos de `N` herramientas tuvieron éxito.
- `--verbose`: imprime cada llamada a herramienta mientras se fuzzea.
- `--update-analysis`: abre la sesión semilla con `update_analysis=true`.

## Catálogo de Características

El servidor expone actualmente `181` herramientas en `36` grupos de características.

### analysis
- `analysis.status`: Obtener estado del análisis.
- `analysis.progress`: Obtener instantánea del progreso del análisis.
- `analysis.update`: Activar actualización asíncrona del análisis.
- `analysis.update_and_wait`: Ejecutar actualización del análisis y esperar a que termine.
- `analysis.abort`: Abortar análisis.
- `analysis.set_hold`: Retener/soltar cola de análisis.

### annotation
- `annotation.rename_function`: Renombrar una función.
- `annotation.rename_symbol`: Renombrar símbolo en dirección.
- `annotation.undefine_symbol`: Indefinir símbolo de usuario en dirección.
- `annotation.define_symbol`: Definir símbolo en dirección.
- `annotation.rename_data_var`: Renombrar variable de datos.
- `annotation.define_data_var`: Definir variable de datos.
- `annotation.undefine_data_var`: Indefinir variable de datos.
- `annotation.set_comment`: Establecer comentario en dirección.
- `annotation.get_comment`: Obtener comentario en dirección.
- `annotation.add_tag`: Agregar etiqueta de datos de usuario en dirección.
- `annotation.get_tags`: Obtener etiquetas en dirección.

### arch
- `arch.info`: Obtener metadatos de arquitectura y plataforma.
- `arch.disasm_bytes`: Desensamblar bytes con arquitectura seleccionada.
- `arch.assemble`: Ensamblar texto de instrucción con arquitectura seleccionada.

### baseaddr
- `baseaddr.detect`: Ejecutar detección de dirección base.
- `baseaddr.reasons`: Obtener razones de detección de dirección base.
- `baseaddr.abort`: Abortar detección de dirección base.

### binary
- `binary.summary`: Obtener resumen de binario/sesión.
- `binary.save`: Guardar la vista binaria actual en una ruta de archivo.
- `binary.functions`: Listar funciones con paginación.
- `binary.strings`: Listar cadenas descubiertas con paginación.
- `binary.search_text`: Buscar texto/bytes sin procesar en una sesión.
- `binary.sections`: Listar secciones con paginación.
- `binary.segments`: Listar segmentos con paginación.
- `binary.symbols`: Listar símbolos con paginación.
- `binary.data_vars`: Listar variables de datos con paginación.
- `binary.get_function_at`: Encontrar función por dirección.
- `binary.get_function_disassembly_at`: Obtener desensamblado completo de la función que contiene una dirección.
- `binary.get_function_il_at`: Obtener IL completo de la función que contiene una dirección.
- `binary.functions_at`: Listar funciones en una dirección.
- `binary.basic_blocks_at`: Listar bloques básicos en una dirección con paginación.

### binja
- `binja.info`: Devolver información de versión/instalación de Binary Ninja.
- `binja.call`: Puente API genérico: llamar a ruta objetivo `bn.*` o `bv.*`.
- `binja.eval`: Evaluar código Python con `bn`, `sessions` y opcional `bv`.

### data
- `data.typed_at`: Obtener variable de datos tipada en una dirección.

### database
- `database.create_bndb`: Crear .bndb desde sesión.
- `database.save_auto_snapshot`: Guardar instantánea automática.
- `database.info`: Obtener estado de la base de datos para la sesión.
- `database.snapshots`: Listar instantáneas de la base de datos.
- `database.read_global`: Leer clave global de cadena de la base de datos.
- `database.write_global`: Escribir clave global de cadena en la base de datos.

### debug
- `debug.parsers`: Listar analizadores de información de depuración válidos para esta vista.
- `debug.parse_and_apply`: Analizar información de depuración y aplicarla a la vista.

### disasm
- `disasm.linear`: Obtener líneas de desensamblado lineal.
- `disasm.function`: Obtener desensamblado completo de la función que contiene una dirección.
- `disasm.range`: Líneas de desensamblado de rango de direcciones.

### external
- `external.library_add`: Añadir biblioteca externa.
- `external.library_list`: Listar bibliotecas externas.
- `external.library_remove`: Eliminar biblioteca externa.
- `external.location_add`: Añadir mapeo de ubicación externa.
- `external.location_get`: Obtener mapeo de ubicación externa.
- `external.location_remove`: Eliminar mapeo de ubicación externa.

### function
- `function.basic_blocks`: Listar bloques básicos de una función con paginación.
- `function.callers`: Llamadores de una función.
- `function.callees`: Llamados de una función.
- `function.variables`: Listar variables de función.
- `function.var_refs`: Listar referencias a variables en MLIL/HLIL.
- `function.var_refs_from`: Listar referencias a variables originadas en una dirección.
- `function.ssa_var_def_use`: Obtener definición y usos de variable SSA.
- `function.ssa_memory_def_use`: Obtener definición y usos de memoria SSA por versión de memoria.
- `function.metadata_store`: Almacenar metadatos de función por clave.
- `function.metadata_query`: Consultar metadatos de función por clave.
- `function.metadata_remove`: Eliminar metadatos de función por clave.

### health
- `health.ping`: Comprobación de estado.

### il
- `il.function`: Listado de funciones IL.
- `il.instruction_by_addr`: Obtener instrucción IL por dirección fuente.
- `il.address_to_index`: Mapear dirección a índice(s) IL.
- `il.index_to_address`: Mapear índice IL a dirección fuente.
- `il.rewrite.capabilities`: Listar soporte de reescritura IL para una función y nivel IL.
- `il.rewrite.noop_replace`: Realizar reemplazo de expresión IL sin operación.
- `il.rewrite.translate_identity`: Traducir IL con callback de mapeo de identidad.

### loader
- `loader.rebase`: Reubicar BinaryView.
- `loader.load_settings_types`: Listar nombres de tipos de configuración del cargador.
- `loader.load_settings_get`: Obtener valores de configuración del cargador.
- `loader.load_settings_set`: Establecer un valor de configuración del cargador.

### memory
- `memory.read`: Leer bytes de la vista (`length <= 65536`).
- `memory.write`: Escribir bytes (hex) en la vista.
- `memory.insert`: Insertar bytes (hex) en la vista.
- `memory.remove`: Eliminar bytes de la vista.
- `memory.reader_read`: Leer valores enteros mediante BinaryReader.
- `memory.writer_write`: Escribir valores enteros mediante BinaryWriter.

### mcp
- `mcp.response_format`: Explicar los campos de resultado de las herramientas (`structuredContent` payload completo, `content[0].text` resumen).

### metadata
- `metadata.store`: Almacenar metadatos por clave.
- `metadata.query`: Consultar metadatos por clave.
- `metadata.remove`: Eliminar metadatos por clave.

### patch
- `patch.assemble`: Ensamblar y parchear bytes de instrucción en dirección.
- `patch.status`: Inspeccionar disponibilidad de parche en dirección.
- `patch.convert_to_nop`: Parchear instrucción a NOP cuando sea compatible.
- `patch.always_branch`: Parchear salto condicional para que siempre salte cuando sea compatible.
- `patch.never_branch`: Parchear salto condicional para que nunca salte cuando sea compatible.
- `patch.invert_branch`: Parchear salto condicional invirtiéndolo cuando sea compatible.
- `patch.skip_and_return_value`: Parchear instrucción para saltar y devolver valor cuando sea compatible.

### plugin
- `plugin.valid_commands`: Listar comandos de complemento válidos en contexto.
- `plugin.execute`: Ejecutar un comando de complemento válido en contexto.

### plugin_repo
- `plugin_repo.status`: Listar repositorios de complementos y estados de complementos.
- `plugin_repo.check_updates`: Comprobar actualizaciones de repositorios de complementos.
- `plugin_repo.plugin_action`: Ejecutar acción de instalar/desinstalar/habilitar/deshabilitar en complemento del repositorio.

### project
- `project.create`: Crear proyecto.
- `project.open`: Abrir proyecto.
- `project.close`: Cerrar proyecto rastreado.
- `project.list`: Listar carpetas/archivos del proyecto.
- `project.create_folder`: Crear carpeta de proyecto.
- `project.create_file`: Crear archivo de proyecto a partir de datos en base64.
- `project.metadata_store`: Almacenar metadatos del proyecto.
- `project.metadata_query`: Consultar metadatos del proyecto.
- `project.metadata_remove`: Eliminar metadatos del proyecto.

### search
- `search.data`: Buscar patrones de bytes sin procesar (cadena hex).
- `search.next_text`: Encontrar la siguiente coincidencia de texto.
- `search.all_text`: Encontrar todas las coincidencias de texto en un rango (regex opcional).
- `search.next_data`: Encontrar la siguiente coincidencia de datos/patrón de bytes.
- `search.all_data`: Encontrar todas las coincidencias de datos/patrón de bytes en un rango.
- `search.next_constant`: Encontrar la siguiente aparición de constante.
- `search.all_constant`: Encontrar todas las apariciones de constante en un rango.

### section
- `section.add_user`: Añadir sección de usuario.
- `section.remove_user`: Eliminar sección de usuario.

### segment
- `segment.add_user`: Añadir segmento de usuario.
- `segment.remove_user`: Eliminar segmento de usuario.

### session
- `session.open`: Abrir un binario y crear una sesión.
- `session.open_bytes`: Abrir una sesión binaria a partir de bytes codificados en base64.
- `session.open_existing`: Abrir otra sesión desde el archivo de una sesión existente.
- `session.close`: Cerrar una sesión abierta.
- `session.list`: Listar sesiones abiertas.
- `session.mode`: Obtener modo de seguridad/determinismo de la sesión.
- `session.set_mode`: Actualizar modo de seguridad/determinismo de la sesión.

### task
- `task.analysis_update`: Iniciar tarea asíncrona de actualización de análisis.
- `task.search_text`: Iniciar tarea asíncrona de búsqueda.
- `task.status`: Obtener estado de la tarea.
- `task.result`: Obtener resultado de la tarea.
- `task.cancel`: Cancelar tarea (mejor esfuerzo).

### transform
- `transform.inspect`: Inspeccionar/procesar pipeline de extracción de transformación.

### type
- `type.parse_string`: Analizar una cadena de tipo única.
- `type.parse_declarations`: Analizar declaraciones C para tipos/variables/funciones.
- `type.define_user`: Definir tipo de usuario a partir de fuente de tipo.
- `type.rename`: Renombrar un tipo.
- `type.undefine_user`: Indefinir un tipo de usuario.
- `type.import_library_type`: Importar tipo desde biblioteca de tipos.
- `type.import_library_object`: Importar tipo de objeto desde biblioteca de tipos.
- `type.export_to_library`: Exportar tipo a una biblioteca de tipos.

### type_archive
- `type_archive.create`: Crear y opcionalmente adjuntar un archivo de tipos.
- `type_archive.open`: Abrir y opcionalmente adjuntar un archivo de tipos.
- `type_archive.list`: Listar archivos de tipos adjuntos.
- `type_archive.get`: Obtener un archivo de tipos rastreado.
- `type_archive.pull`: Extraer tipos de un archivo de tipos.
- `type_archive.push`: Insertar tipos en un archivo de tipos.
- `type_archive.references`: Consultar referencias entrantes/salientes del archivo para un tipo.

### type_library
- `type_library.create`: Crear y opcionalmente adjuntar una biblioteca de tipos.
- `type_library.load`: Cargar y opcionalmente adjuntar una biblioteca de tipos.
- `type_library.list`: Listar bibliotecas de tipos adjuntas a la vista.
- `type_library.get`: Obtener una biblioteca de tipos rastreada.

### uidf
- `uidf.parse_possible_value`: Analizar cadena de conjunto de valores posibles informados por el usuario.
- `uidf.set_user_var_value`: Establecer valor de variable de usuario de función.
- `uidf.clear_user_var_value`: Limpiar valor de variable de usuario de función.
- `uidf.list_user_var_values`: Listar todos los valores de variables de usuario de una función.

### undo
- `undo.begin`: Iniciar transacción de deshacer.
- `undo.commit`: Confirmar transacción de deshacer.
- `undo.revert`: Revertir transacción de deshacer.
- `undo.undo`: Realizar deshacer.
- `undo.redo`: Realizar rehacer.

### value
- `value.reg`: Obtener valor de registro en/después de una dirección.
- `value.stack`: Obtener contenido de pila en/después de una dirección.
- `value.possible`: Obtener conjunto de valores posibles IL en una dirección.
- `value.flags_at`: Obtener estado de lectura/escritura de flags IL elevados en una dirección.

### workflow
- `workflow.list`: Listar flujos de trabajo registrados.
- `workflow.describe`: Describir topología y configuración del flujo de trabajo.
- `workflow.clone`: Clonar flujo de trabajo.
- `workflow.insert`: Insertar actividades antes de una actividad.
- `workflow.insert_after`: Insertar actividades después de una actividad.
- `workflow.remove`: Eliminar actividad del flujo de trabajo.
- `workflow.graph`: Resumir gráfico del flujo de trabajo.
- `workflow.machine.status`: Obtener estado de la máquina de flujo de trabajo.
- `workflow.machine.control`: Controlar runtime de la máquina de flujo de trabajo.

### xref
- `xref.code_refs_to`: Referencias de código a una dirección.
- `xref.code_refs_from`: Referencias de código desde una dirección.
- `xref.data_refs_to`: Referencias de datos a una dirección.
- `xref.data_refs_from`: Referencias de datos desde una dirección.

## Contacto

Para más información, contacta a Tim Blazytko ([@mr_phrazer](https://x.com/mr_phrazer)).