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
• 44 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
• 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 - 44 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 (44 Total)

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

Binary Management

Code Analysis (Consolidated)

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

Comments (Consolidated)

Variables (Consolidated)

Types (Consolidated)

Function Discovery

Symbol Management

Binary Information

Data Analysis

Patching

Navigation & Bookmarks

Task Management (Experimental)

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.

MCP Prompts (7 Total)

Pre-built prompts guide LLMs through structured analysis workflows.

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:

Configuration

Binary Ninja Settings

Open Edit → Preferences → binassistmcp:

Environment Variables

export BINASSISTMCP_SERVER__HOST=localhost
export BINASSISTMCP_SERVER__PORT=8000
export BINASSISTMCP_SERVER__TRANSPORT=streamablehttp
export BINASSISTMCP_BINARY__MAX_BINARIES=10

Usage

Starting the Server

Via Binary Ninja Menu:

1. Tools → BinAssistMCP → Start Server

2. Check log panel for: `BinAssistMCP server started on http://localhost:8000`

Auto-Startup:

Server starts automatically when Binary Ninja loads a file (configurable).

Connecting MCP Clients

Streamable HTTP (Default):

http://localhost:8000/mcp

Server-Sent Events:

http://localhost:8000/sse

Claude Desktop Configuration

Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`):

{
  "mcpServers": {
    "binassist": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Integration Examples

Most binary-specific tools require the context name in `filename`. `list_binaries` returns these names, but it is not an initialization requirement: direct filename-based calls refresh the context from Binary Ninja automatically when necessary.

Basic Function Analysis

User: "Analyze the main function and explain what it does"

Claude uses:
1. list_binaries() - obtain the context filename
2. get_functions(filename='sample.bndb') - find main
3. get_code(filename='sample.bndb', function_name_or_address='main', format='decompile')
4. xrefs(filename='sample.bndb', address_or_name='main', direction='from')
5. analyze_function(filename='sample.bndb', function_name_or_address='main')

Vulnerability Research

User: "Find buffer overflow vulnerabilities in input handling functions"

Claude uses:
1. search_functions_advanced(filename='sample.bndb', search_term='strcpy', search_in='calls')
2. get_code(filename='sample.bndb', function_name_or_address='handler', format='decompile')
3. variables(filename='sample.bndb', action='list', function_name_or_address='handler')
4. comments(filename='sample.bndb', action='set', address='0x401000', text='Unchecked copy')

Protocol Reverse Engineering

User: "Analyze the network protocol used by this binary"

Claude uses the trace_network_data prompt:
1. Identifies send/recv call sites
2. Traces data flow from handlers to network I/O
3. Reconstructs message structures
4. Checks for network vulnerabilities

Troubleshooting

Server Issues

Performance

• Memory usage: Reduce `max_binaries` setting
• Code retrieval: `get_code` returns loaded analysis immediately and falls back rather than triggering analysis

Logs

Check Binary Ninja's Log panel for detailed error messages.

Contributing

1. Fork the repository

2. Create a feature branch

3. Follow existing code patterns (Pydantic models, type hints, docstrings)

4. Test with multiple binary types

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.