BinAssistMCP

Comprehensive Model Context Protocol (MCP) server for Binary Ninja with AI-powered reverse engineering capabilities

Summary

BinAssistMCP is a powerful bridge between Binary Ninja and Large Language Models (LLMs) like Claude, providing comprehensive reverse engineering tools through the Model Context Protocol (MCP). It enables AI-assisted binary analysis by exposing Binary Ninja's advanced capabilities through Server-Sent Events (SSE) and Streamable HTTP transports.

Key Features

• MCP 2025-11-25 Compliant: Full support for tool annotations, resources, and prompts
• Dual Transport Support: SSE (Server-Sent Events) and Streamable HTTP transports
• 45 Consolidated Tools: Streamlined Binary Ninja API wrapper with unified tool design
• 8 MCP Resources: Browsable, cacheable binary metadata
• 7 Guided Prompts: Pre-built workflows for common reverse engineering tasks
• Multi-Binary Sessions: Concurrent analysis of multiple binaries with intelligent context management
• Context-Rich Code Output: Function signatures and Binary Ninja comments are embedded in code results
• Analysis-Safe Queries: Code retrieval uses already-loaded IL and never forces global reanalysis
• Session-Independent Discovery: Direct tool calls discover open Binary Ninja views without requiring a prior listing call
• Nonblocking Binary Opens: Large binaries and .bndb databases open asynchronously with pollable operation status
• Thread-Safe: RLock-based synchronization for concurrent access
• Auto-Integration: Seamless Binary Ninja plugin with automatic startup capabilities

Use Cases

• AI-Assisted Reverse Engineering: Leverage LLMs for intelligent code analysis and documentation
• Protocol Analysis: Trace network data flows and reconstruct protocol structures
• Vulnerability Research: Systematic security audits with guided workflows
• Automated Binary Analysis: Script complex analysis workflows with natural language
• Code Understanding: Generate comprehensive documentation and explanations

---

Architecture

src/binassist_mcp/
├── server.py        # FastMCP server - SSE/Streamable HTTP transport, tool registration
├── tools.py         # Binary Ninja API wrapper - 45 MCP tools
├── plugin.py        # Binary Ninja plugin integration
├── context.py       # Thread-safe multi-binary session management
├── config.py        # Pydantic configuration with Binary Ninja settings
├── prompts.py       # 7 guided workflow prompts
├── resources.py     # 8 MCP resource definitions
├── cache.py         # Cache primitives (not currently connected to MCP tools)
├── tasks.py         # Task lifecycle support (tool dispatch is not yet implemented)
├── logging.py       # Binary Ninja logging integration
└── utils.py         # Utility functions

__init__.py          # Plugin entry point (root level)

---

Tools (45 Total)

BinAssistMCP provides 45 tools organized into functional categories. Tools include MCP annotations (readOnlyHint, idempotentHint) to help clients make informed decisions.

Binary Management

| Tool | Description | |------|-------------| | list_binaries | Synchronize with Binary Ninja and list all loaded binary files | | get_binary_info | Check analysis status and metadata | | get_binary_status | Poll a queued open by operation ID, path, or name and report analysis progress | | open_binary | Queue a nonblocking binary or .bndb open; raw binaries require a destination bndb_path | | update_analysis_and_wait | Force analysis update and wait for completion | | export_program | Export the patched binary or Binary Ninja database to disk |

By default, open_binary validates its paths, schedules the Binary Ninja open, and immediately returns an operation_id with status="opening". Poll get_binary_status(operation_id) until it reports ready or failed. When ready, its name field is the final context name to pass to analysis tools. Concurrent requests for the same path reuse the active operation. Set wait_for_analysis=true only when legacy blocking behavior is explicitly required.

Code Analysis (Consolidated)

| Tool | Description | |------|-------------| | get_code | Read analysis-safe code with signatures and comments; supports decompile, hlil, mlil, llil, disasm, and pseudo_c | | get_function_low_level_il | Get Low-Level IL for a function | | get_function_signature | Generate the native masked byte signature for a function | | analyze_function | Comprehensive function analysis with control flow and complexity metrics | | get_basic_blocks | Get basic block information for control flow analysis | | get_function_stack_layout | Get stack frame layout with variable offsets |

get_code behavior

get_code is a read-only query. It does not clear analysis_skipped, request IL generation, or run global analysis. For format="decompile", it returns already-loaded HLIL when available, then falls back through MLIL and LLIL to instruction-aligned disassembly. Use update_analysis_and_wait explicitly when fresh analysis is desired.

The code string starts with the current function signature and includes function-level and instruction-level Binary Ninja comments. The response contains:

• function and address: resolved function identity
• format: requested format
• actual_format: representation actually returned, or null when an explicitly requested IL is unavailable
• fallback_used: whether decompile used a lower-level representation
• code: rendered code, signature, and comments
• note: present when a fallback explains why and what was returned

Cross-References (Consolidated)

| Tool | Description | |------|-------------| | xrefs | Unified cross-references with direction set to to, from, or both; optionally includes call relationships |

Comments (Consolidated)

| Tool | Description | |------|-------------| | comments | Unified comment management - actions: get, set, list, remove, set_function |

Variables (Consolidated)

| Tool | Description | |------|-------------| | variables | Unified variable management - actions: list, create, rename, set_type; rename supports local/global via scope |

Types (Consolidated)

| Tool | Description | |------|-------------| | types | Unified type management - actions: create, create_enum, create_typedef, create_class, add_member, info, list | | get_classes | List all classes and structures |

Function Discovery

| Tool | Description | |------|-------------| | get_functions | List all functions with metadata | | search_functions_by_name | Find functions by name pattern | | get_functions_advanced | Advanced filtering by size, complexity, parameters | | search_functions_advanced | Multi-target search (name, comments, calls, variables) | | get_function_statistics | Comprehensive statistics for all functions |

Symbol Management

| Tool | Description | |------|-------------| | rename_symbol | Rename functions and data variables | | batch_rename | Rename multiple symbols in one operation | | get_namespaces | List namespaces and symbol organization |

Binary Information

| Tool | Description | |------|-------------| | get_imports | Import table grouped by module | | get_exports | Export table with symbol information | | get_strings | Paginated string extraction | | search_strings | Search strings by pattern | | get_segments | Memory segment layout | | get_sections | Binary section information | | get_entry_points | List all binary entry points |

Data Analysis

| Tool | Description | |------|-------------| | create_data_var | Define data variables at addresses | | get_data_vars | List all defined data variables | | get_data_at | Read and analyze raw data | | search_bytes | Search for byte patterns in binary |

Patching

| Tool | Description | |------|-------------| | patch_bytes | Patch raw bytes in the binary at an address | | assemble_code | Assemble instruction text at an address and optionally patch it |

Navigation & Bookmarks

| Tool | Description | |------|-------------| | get_current_address | Get current cursor position with context | | get_current_function | Identify function at current address | | bookmarks | Unified bookmark management - actions: list, set, remove |

Task Management (Experimental)

| Tool | Description | |------|-------------| | start_task | Create a placeholder background task record; tool_name dispatch is not implemented yet | | get_task_status | Check status of async operations | | list_tasks | List all pending/running tasks | | cancel_task | Cancel a running task |

These APIs currently exercise task lifecycle management only. They do not execute the named MCP tool in the background.

---

MCP Resources (8 Total)

Resources provide browsable, cacheable data that clients can access without tool calls.

| URI Pattern | Description | |-------------|-------------| | binassist://{filename}/triage_summary | Complete binary overview | | binassist://{filename}/functions | All functions with metadata | | binassist://{filename}/imports | Import table | | binassist://{filename}/exports | Export table | | binassist://{filename}/strings | String table | | binja://{filename}/info | Binary metadata (arch, platform, entry point) | | binja://{filename}/segments | Memory segments with permissions | | binja://{filename}/sections | Binary sections |

---

MCP Prompts (7 Total)

Pre-built prompts guide LLMs through structured analysis workflows.

| Prompt | Arguments | Description | |--------|-----------|-------------| | analyze_function | function_name, filename | Comprehensive function analysis workflow | | identify_vulnerability | function_name, filename | Security audit checklist (memory safety, input validation, crypto) | | document_function | function_name, filename | Generate Doxygen-style documentation | | trace_data_flow | address, filename | Track data dependencies and taint propagation | | compare_functions | func1, func2, filename | Diff two functions for similarity analysis | | reverse_engineer_struct | address, filename | Recover structure definitions from usage patterns | | trace_network_data | filename | Trace POSIX/Winsock send/recv for protocol analysis |

Example: Network Protocol Analysis

The trace_network_data prompt guides analysis of network communication:

1. Identify Network Functions: Finds POSIX (send/recv/sendto/recvfrom) and Winsock (WSASend/WSARecv) calls
2. Trace Call Stacks: Maps application handlers down to network I/O
3. Analyze Buffers: Identifies protocol structures (headers, length fields, TLV encoding)
4. Reconstruct Protocols: Generates C struct definitions for message formats
5. Security Assessment: Checks for buffer overflows, integer issues, information disclosure

---

Installation

Prerequisites

• Binary Ninja: Version 5000 or higher
• Python: 3.10+ (typically bundled with Binary Ninja and required by the pinned MCP SDK)
• Platform: Windows, macOS, or Linux

NOTE: Windows users should start with: BinAssistMCP on Windows

Option 1: Binary Ninja Plugin Manager (Recommended)

1. Open Binary Ninja
2. Navigate to Tools → Manage Plugins
3. Search for "BinAssistMCP"
4. Click Install
5. Restart Binary Ninja

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/symgraph/BinAssistMCP.git
cd BinAssistMCP

# Install dependencies
pip install -r requirements.txt

Copy to your Binary Ninja plugins directory:

| Platform | Path | |----------|------| | Windows | %APPDATA%\Binary Ninja\plugins\ | | macOS | ~/Library/Application Support/Binary Ninja/plugins/ | | Linux | `~/.binar