Binary Ninja Headless MCP

A headless Binary Ninja server that speaks MCP (Model Context Protocol), giving AI agents full access to deep reverse-engineering workflows — disassembly, IL, patching, types, xrefs, and more — without a GUI.

Designed to run in the same Docker container as the agent runtime. No sidecars, no extra services.

This entire project---code, tests, and documentation---is 100% vibe coded.

Why

Existing Binary Ninja MCP servers are either GUI-bound or expose a limited tool surface. This server is headless-only and designed for agent-driven workflows in sandboxed VM/container environments: the agent gets full control over the analysis system, automating large parts of reverse engineering while you interactively discuss and steer the process.

The goal is an interface where agents can inspect, refine, and extend an analysis over time — updating types, symbols, and metadata, improving the analysis database incrementally, applying patches and iterating safely with undo/redo, and running custom scripts when a workflow needs something bespoke.

Features

• 181 tools across 36 feature groups: analysis, disassembly, IL, patching, undo/redo, types, workflows, memory, search, xrefs, scripting, and more.
• Read-only by default with safe mutation workflows (undo/redo, transactions).
• Scripting access via binja.eval and binja.call for anything the tool catalog doesn't cover.
• Stdio and TCP transports.
• Zero runtime dependencies beyond Binary Ninja itself.
• Fake backend mode for CI and development without a Binary Ninja license.

Prerequisites

• Python 3.11+
• A Binary Ninja installation with a headless-capable license and the binaryninja Python module importable in your runtime (for real analysis)
• For CI/development without Binary Ninja, use fake backend mode

Installation

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

Or install directly from the repo root without cloning:

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

Quick Start

Stdio transport (default):

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 mode (no Binary Ninja required):

python3 binary_ninja_headless_mcp.py --fake-backend

Use With AI Agents

This server speaks standard MCP over stdio (default) or tcp, so any MCP-capable agent host can use it.

Claude Code

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

Or add it to your project's .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

Generic MCP Host

• Register a server named binary_ninja_headless_mcp.
• Use command python3 with args ["binary_ninja_headless_mcp.py"] when cwd is the repo root, or use an absolute script path in args.
• Set cwd to the repo path if you want relative paths like samples/ls to resolve correctly.
• Use stdio transport unless your host requires TCP.
• For fake mode (no Binary Ninja installed), append --fake-backend.
• Verify connectivity by calling health.ping, then session.open.

Docker Co-Location Pattern

Recommended deployment model: run the agent process and this MCP server in the same container image.

Example baseline:

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

If you need real Binary Ninja analysis in-container, add your Binary Ninja runtime + license setup in this same image and start the agent with this MCP server configured.

MCP Methods

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

tools/list behavior:

• Without explicit pagination params, returns the full tool catalog.
• If offset or limit is provided, uses paginated output (offset=0, limit=50 default in paged mode).
• Supports filtering via:
  • prefix (for example binary.)
  • query (substring match against tool name/description)
• Returns pagination metadata: offset, limit, total, has_more.
• When a page is truncated (has_more=true), includes next_offset and a notice hint.

Tool call response behavior:

• structuredContent is the canonical full payload.
• content[0].text is a compact summary string (not full JSON duplication).
• This split is intentional to keep context usage smaller while still exposing full machine-readable data.

Quality And Testing

This repository is well tested and has enforced quality gates.

• Test suite: run pytest --collect-only -q for the current collected test count.
• CI workflow enforces:
  • ruff format --check .
  • ruff check .
  • pytest
• CI uses BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 so checks run without requiring Binary Ninja installation.
• Additional structural tests verify tool registry consistency and backend reachability.

Context Controls

• Read-only mode is the default for opened sessions (read_only=true).
• binary.basic_blocks_at and function.basic_blocks are paginated (offset/limit).
• memory.read has a hard response cap: length <= 65536.

Limitations

• Enterprise APIs are currently not covered.
• Debugger APIs are currently not covered.

Security Model

• MCP communication (stdio/tcp) is unauthenticated by default.
• The server exposes arbitrary scripting via binja.eval and broad API access via binja.call.
• This is by design for trusted, containerized agent environments.
• Do not expose this server directly to untrusted users or networks.

Local Dev Workflow

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

Feature Fuzzer

Use the built-in MCP feature fuzzer to exercise a broad tool surface against samples/ls.

Real Binary Ninja backend:

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

Fake backend smoke run:

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

Write a JSON coverage report:

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

Useful flags:

• --min-success-tools N: exits non-zero if fewer than N tools succeeded.
• --verbose: print each tool call while fuzzing.
• --update-analysis: open the seed session with update_analysis=true.

Feature Catalog

The server currently exposes 181 tools across 36 feature groups.

analysis

• analysis.status: Get analysis status.
• analysis.progress: Get analysis progress snapshot.
• analysis.update: Trigger async analysis update.
• analysis.update_and_wait: Run analysis update and wait for completion.
• analysis.abort: Abort analysis.
• analysis.set_hold: Hold/release analysis queue.